designing beautiful rest apis

DESIGNING BEAUTIFULREST APIs

@tomekcejner

THE PRESENTER

THE PRESENTERTOMEK CEJNER@tomekcejnerwww.japko.net

tomek@japko.net

THE PRESENTERTOMEK CEJNER@tomekcejnerwww.japko.net

tomek@japko.net

FASHION

WHAT REST MEANS

NO FRAMEWORKS

APPLICATIONS

APPLICATIONSGOING OPEN

APPLICATIONSGOING OPENGOING BIG

LOOSE COUPLING

LOOSE COUPLINGSMALLER CODEBASE

REUSABILITY

WEB SERVICES

WORLDS BIGGEST APP EVER

WORLD WIDE WEB

WHAT IS REST?

A PROTOCOL?

A PROTOCOL?NO

A SPECIFICATION?

A SPECIFICATION?NO

ARCHITECTURAL STYLE

ROY T. FIELDINGPHD DISSERTATION

http://www.w3.org/Protocols/rfc2616/rfc2616.html

BUILDING ARCHITECTURE

BUILDING ARCHITECTUREFROM SCRATCH

BUILDING ARCHITECTUREFROM SCRATCHFROM WHOLE

CONSTRAINTS

CONSTRAINTSCLIENT-SERVER

STATELESS

STATELESSCACHEABLE

UNIFORM INTERFACE

RESOURCE

http://www.example.com/blogs/423/entries/12340 http://www.example.com/sales/2004/Q4http://www.example.com/bugs/by-state/open

http://api.example.com/places/42.089199,93.076172http://api.example.com/color-blends/yellow;blue

http://api.example.com/items?price_min=0&price_max=599

http://api.example.com/auctions/239841/cancel

RICHARDSON MATURITY MODEL

http://www.crummy.com/writing/speaking/2008-QCon/act3.html

LEVEL 0

LEVEL 0HELL

POST /auctionServiceAPIEndpoint HTTP/1.1

<query> <params> <name>Macbook Air</name> <price_from>0</price_from> <price_to>1000</price_to> </params></query>

HTTP/1.1 200 OK

<items> <item> <id>123</id> <name>Macbook Air</name>

LEVEL 1

LEVEL 1URI

POST /auctions/1234/read

POST /auctions/1234/readGET /auctions/1234/read

POST /auctions/1234/readGET /auctions/1234/readPOST /auctions/create

POST /auctions/1234/readGET /auctions/1234/readPOST /auctions/createPOST /auctions/1234/update

LEVEL 2HTTP

/auctions

/auctions/auctions/1234

GETPOST

GETPOSTPUT

DELETE

GETPOSTPUT

DELETEHEAD

GETPOSTPUT

DELETEHEAD

OPTIONS

GETPOSTPUT

DELETEHEAD

OPTIONSPATCH

GET /auctions

GET /auctionsGET /auctions/1234

GET /auctionsGET /auctions/1234GET /auctions?search=Macbook+Air

SAFE + IDEMPOTENT

TESLA MODEL SIT HAS A RESTFUL API

GET http://api.flickr.com/services/rest?method=flickr.photos.people.add&api_key=xxx&photo_id=yyy&user_id=zzz

DELETE

DELETE /auctions/1234

DELETE

DELETE /auctions/1234

HTTP/1.1 204 No Content

DON’T DO THIS AT HOME

DELETE

DELETEIDEMPOTENT

NOT SAFE

POST /items{! "name" : "Macbook Air 2010",! "condition" : "NEW",! "price" : 499}

201 CreatedLocation: http://api.alledrogo.com/items/1235

NOT IDEMPOTENTPOST

NOT IDEMPOTENTNOT SAFE

PUT /items/1235

{ "name" : "Macbook Air 2010",! "condition" : "LIKE_NEW",! "price" : 498}

PUT /users/joe

{ “first_name” : “Joe”, “last_name” : “Smith”}

PUTIDEMPOTENT

NOT SAFE

POST: ID FROM SERVER

POST: ID FROM SERVERPUT: ID FROM CLIENT

OPTIONS

OPTIONSDISCOVERY

OPTIONS /users HTTP/1.1

...HTTP/1.1 204 No ContentAllow: GET, POST, PUT

/users /users/456

DELETE

GET ALL GET USER

CREATE NEW -

- UPDATE

DELETE ALL DELETE USER

HTTP STATUS CODES

SUCCESS

SUCCESS200 OK

SUCCESS200 OK201 CREATED

SUCCESS200 OK201 CREATED202 ACCEPTED

SUCCESS200 OK201 CREATED202 ACCEPTED204 NO CONTENT

201 CREATEDPOST /items/1234/bids{! "amount" : 602.99}

201 CreatedLocation: http://api.alledrogo.com/items/1234/bids/100001{! "cap_amount" : 602.99,! "current_bid" : 510,! "winning" : true}

REDIRECT

REDIRECT301 MOVED PERMANENTLY

REDIRECT301 MOVED PERMANENTLY303 SEE OTHER

REDIRECT301 MOVED PERMANENTLY303 SEE OTHER304 NOT MODIFIED

REDIRECT301 MOVED PERMANENTLY303 SEE OTHER304 NOT MODIFIED307 TEMPORARY REDIRECT

USER ERROR

USER ERROR400 BAD REQUEST

USER ERROR400 BAD REQUEST401 UNAUTHORIZED

USER ERROR400 BAD REQUEST401 UNAUTHORIZED403 FORBIDDEN

http://cropp.com/404

405 METHOD NOT ALLOWED

409 CONFLICT

410 GONE

SERVER ERROR

SERVER ERROR500 INTERNAL SERVER ERROR

SERVER ERROR500 INTERNAL SERVER ERROR503 SERVICE UNAVAILABLE

DON’T IGNORE HTTP STATUS

http://api.flickr.com/services/rest?method=flickr.photos.people.add&api_key=xxx&photo_id=yyy&user_id=zzz

HTTP/200 OK

<?xml version="1.0" encoding="utf-8" ?><rsp stat="fail"> <err code="100" msg="Invalid API Key (Key has invalid format)" /></rsp>

HTTP/200 OK

LEVEL 3

LEVEL 3HYPERMEDIA

LINKING

SELF DESCRIBED CAPABILITIES

INTERCONNECTION

PRESENTATIONXHTML

XMLATOM

GET /items?q=macbook+air+new{! "results" : [! ! {! ! ! "id" : 1234,! ! ! "name" : "Macbook Air 2010 LIKE NEW",! ! ! "price" : "499"! ! }! ]}

NO HYPERMEDIA

GET /items?q=macbook+air+new{! "results" : [! ! {! ! ! "_links" : [! ! ! ! { "rel" : "self", "uri" : "/items/1234" },! ! ! ! { "rel" : "bids", "uri" : "/items/1234/bids" },! ! ! ! { "rel" : "highest_bid", "uri" : "/items/1234/bids?q=winning" }! ! ! ],! ! ! "name" : "Macbook Air 2010 LIKE NEW",! ! ! "price" : "499"! ! }! ]}

WITH HYPERMEDIA

GET /items/1234{! "_links" : [! ! { "rel" : "self", "uri" : "/items/1234" },! ! { "rel" : "bids", "uri" : "/items/1234/bids"},! ! { "rel" : "seller", "uri" : "/users/9876"}! ],! "name" : "Macbook Air 2010 LIKE NEW",! "price" : "499"}

GET /users/9876{! "_links" : [! ! { "rel" : "self", "uri" : "/users/9876" },! ! { "rel" : "ratings", "uri" : "/users/9876/ratings" }! ! { "rel" : "messages", "uri" : "/users/9876/messages" }! ! { "rel" : "listings", "uri" : "/users/9876/listings" }! ],! "name" : "John Doe"}

POST /items/1234/bids{! "amount" : 602.99}

201 CreatedLocation: http://api.alledrogo.com/items/1234/bids/100001{! "_links" : [! ! { "rel" : "self", "uri" : "/items/1234/bids/100001" },! ! { "rel" : "item", "uri" : "/items/1234" },! ]! "cap_amount" : 602.99,! "current_bid" : 510,! "winning" : true}

DOMAIN APPLICATION PROTOCOL

HATEOAS

HATEOASHYPERMEDIA

ASTHE ENGINE

HATEOASHYPERMEDIA

ASTHE ENGINE

OF APPLICATION STATE

IN PRACTICE

AUCTION SERVICE - USERS

doGetMyDatadoGetUserIDdoGetUserItemsdoShowUserdoShowUserPage

AUCTION SERVICE - USERS

doGetMyDatadoGetUserIDdoGetUserItemsdoShowUserdoShowUserPage

GET /users/meGET /users?name=czesioGET /users/123456/itemsGET /users/123456/detailsGET /users/123456/aboutpage

AUCTION SERVICE - MY AUCTIONS

doGetFavouriteCategoriesdoGetFavouriteSellersdoGetMyBidItemsdoGetMyWatchItems doGetMySoldItemsdoRemoveFromWatchList

AUCTION SERVICE - MY AUCTIONS

doGetFavouriteCategoriesdoGetFavouriteSellersdoGetMyBidItemsdoGetMyWatchItems doGetMySoldItemsdoRemoveFromWatchList

GET /users/me/favorites/categoryGET /users/me/favorites/sellersGET /users/me/bidsGET /users/me/items/watchingGET /users/me/items/soldDELETE /users/me/items/watching/1

AUCTION SERVICE - BIDDING

doBidItemdoRequestCancelBid

AUCTION SERVICE - BIDDING

doBidItemdoRequestCancelBid

POST /items/54321/bidsDELETE /items/54321/bids/678

BEYOND CRUD

COPYGET /items/5001

HTTP/1.1 200 OK{ “_links” : [ { “rel” : “self”, “href” : “/items/5001” }, { “rel” : “duplicate”, “href” : “/items/5001/duplicate;t=37489231614874” } ], “name” : “MacBook Air”, “price” : 599}

POST /items/5001/duplicate;t=37489231614874

HTTP/1.1 201 CreatedLocation: /items/5002

SNAPSHOT

PUT /items/5002

{ “name” : “MacBook Air”, “price” : 399}

HTTP/1.1 204 No Content

SNAPSHOTGET /items/5002

{ “_links” : [ { “rel” : “self”, “href” : “/items/5002” }, { “rel” : “duplicate”, “href” : “/items/5002/duplicate;t=98435943498” }, { “rel” : “previous”, “href” : “/items/5002/s1” }, { “rel” : “undo”, “href” : “/items/5002/undo;t=92312093” }, ], “name” : “MacBook Air”, “price” : 599}

POST /items/5002/undo;t=92312093

HTTP/1.1 303 See OtherLocation: /items/5002

ASYNCHRONOUS OPERATION

ASYNCHRONOUS OPERATIONPOST /projects/123/tasks{ “type” : “REPORT”, “date_from” : “20130101”, “date_to” : “20130331”}

HTTP/1.1 202 Accepted{ “state” : “PENDING”, “ping-after” : “2013-04-12T17:02:32Z” “_links” : [ { “rel” : ”outcome”, “href” : “http://api.example.com/reports/882” }, ]}

MEDIA TYPES

Content-Type: application/vnd.alledrogo+xml

MEDIA TYPES

Content-Type: application/vnd.alledrogo+xmlContent-Type: text/html

REST VS SOAP/RPC

REST VS SOAP/RPCCOMPLEMENT, NOT CONCURRENT

NATURE OF THE WEB

CALL IT REST

CALL IT RESTWHEN DOING IT REST

THANK YOU!

designing beautiful rest apis

http statushttp

post putdelete

restful api

http status codes

macbook air01000

delete user

richardson maturity

peopl ok

Technology

webapp #4 : consuming rest apis

consuming rest apis - sddconf.com

consumindo apis rest com ruby

performance testing rest apis

pragmatic rest apis

building automated rest apis with python

rest apis, girls who code

rest apis in laravel 101

sharepoint 2013 rest apis

tdc2015: testes em apis rest com rest-assured

cakefest 2013 - a-z rest apis

bootstrat rest apis with laravel 5

otm and rest apis

documenting rest apis

consuming rest apis for all interpretations of rest

futureproofing rest apis

sgce 2015 rest apis

clase04 apis-rest

building beautiful rest apis with asp.net core

introduccion apis rest