REST, RESTful API

API

Developers as Customers

Make APIs Easy to Learn

Design APIs Well

Bad designed APIs...

/getUser/getAllUsers/findUser/findUserAccounts/deleteUser/changeUserPass...

API Consumers

API Designers

Simplicity

REST is your friend

Base URLs per each resource

Collection

/users

Entity

/users/hossein/users/13246

HTTP Verbs

POST

GET

PUT

DELETE

PATCH...

C.R.U.D. Operations

C. POST

R. GET

U. PUT

D. DELETE

PUT is also used for creating

PATH for partial updates

Verb

ResourcePOST GET PUT DELETE

/usersNew User List Users ? Delete

Everybody

/users/hossein? Show Hossein :)

Update / Create Hossein

Delete Hossein :(

Resources as Nouns

Plural Nouns

Stop using Verbs

Verb

ResourcePOST GET PUT DELETE

/usersNew User List Users ? Delete

Everybody

/users/hossein? Show Hossein :)

Update / Create Hossein

Delete Hossein :(

Associations

Chaining resources together

Chaining resources together

/users/hossein/accounts

Nesting too much

Complexity may arise

Keep Base URL Simple

?

Query String

?

Query String

/users?state=pending

Params in Headers

Pagination

Offset / Limit

Page number

Start / Count

HATEOAS

Hypermedia As The Engine Of Application State

GET /account/12345

HTTP/1.1 HTTP/1.1 200 OK <?xml version="1.0"?> <account> <account_number>12345</account_number> <balance currency="usd">100.00</balance> <link rel="deposit" href="/account/12345/deposit" /> <link rel="withdraw" href="/account/12345/withdraw" /> <link rel="transfer" href="/account/12345/transfer" /> <link rel="close" href="/account/12345/close" /> </account>

GET /account/12345

HTTP/1.1 HTTP/1.1 200 OK <?xml version="1.0"?> <account> <account_number>12345</account_number> <balance currency="usd">-30.00</balance> <link rel="deposit" href="/account/12345/deposit" /></account>

Versioning

Date

/2014-04-05/...

Decimal Point

/v1.0/...

In Query String

…?v=1

Integer :)

/v1//v2/

Leftmost in the URI

Header

Be Explicit

Limiting Entity Fields

Limiting Entity Fields

/users:(id,first-name)

Limiting Entity Fields

/users?fields=id,first-name

Formats(JSON, XML)

Header

Content-Type: application/json

Extension

/users.json

Query String

/users?type=json

Error Handling

HTTP Status Codes

Error Messages

Linking to comprehensive explanation

Domain

Domain

api.example.com

Domain

dev.example.com

Domain

example.com/api/