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/
Top Related