Download - RESTFul APIs
RESTful APIs
Maceió Dev Meetup December 17, 2014
about.me/endersonmaia
What I’m going to talk
30 minutes to• REST
• Constraints
• Richard Maturity Model (RMM)
• HTTP Methods
• HTTP Satus Codes
• Resource Naming
• Format
• Linking
• …
RESTRepresentational State Transfer
(Roy Fielding, 2000)
Constraints
Client–server
Stateless
Cacheable
Layered system
Uniform interface
Uniform interface• Resource-Based
• Manipulation of Resources Through Representations
• Self-descriptive Messages
• Hypermedia as the Engine of Application State (HATEOAS)
RMM Richardson
Maturity Model
Level 0 The swamp of POX
Level 0 The swamp of POX
$ curl -X POST -d \ "<?xml version=“1.0"?> \ <methodCall> \ <methodName>examples.getStateName</methodName> \ <params> \ <param> \ <value><i4>40</i4></value> \ </param> \ </params> \ </methodCall>" http://api.example.com
Level 1 Resources
Level 1 Resources
• GET - http://host/person?action=add?name=John&age=25
• GET - http://host/city/delete
Level 2 HTTP Verbs
Level 2 HTTP Verbs
• GET - http://host/users
• PUT - http://host/users
• DELETE - http://host/users
Level 3 Hypermedia Controls
HTTP Methods
GET
POST
DELETE
PUT
PATCH
OPTIONS
– Leonard Richardson, 2007
"OPTIONS is a promising idea that nobody uses."
HEAD
HTTP Status Codes
2XX
2XX
• 200 - OK
• 201 - Created
• 202 - Accepted
• 204 - No Content
3XX
3XX
• 301 - Moved Permanently
• 304 - Not Modified
4XX
4XX• 400 - Bad Request
• 401 - Unauthorized
• 403 - Forbidden
• 404 - Not Found
• 409 - Conflict
5XX
5XX
• 500 - Internal Server Error
• 501 - Not Implemented
HTTP Headers
HTTPMethod x Status
More …
Verbs
Verbs• POST - to create (INSERT) a new resource
• GET - to recover (SELECT) a specific resource
• PUT/PATCH - to UPDATE a specific resource
• DELETE - to DELETE a specific resource
Resource Naming
Resource Naming• POST http://example.com/customers
• GET http://example.com/customers/33245
• GET|PUT|DELETE http://example.com/products/66432
• GET http://example.com/customers/33245/orders
• POST http://example.com/customers/33245/orders/8769/lineitems
• GET http://example.com/customers/33245/orders/8769/lineitems/1
Resource Naming Anti-Pattern
• GET http://api.example.com/services?op=update_customer&id=12345&format=json
• GET http://api.example.com/update_customer/12345
• GET http://api.example.com/customers/12345/update
• PUT http://api.example.com/customers/12345/update
Response
Format
Format
• XML (Atom, …)
• JSON (JSON-LD, HAL, …)
Linking
HATEOAS
Hypermedia As The Engine Of Application State
HATEOAS
HATEOAS
Idempotence &
Safe Methods
What’s missing ?
What’s missing ?• More about HTTP Header
• HTTP Authentication samples
• Using Tokens
• Versioning strategies
• ?
References• http://stateless.co/hal_specification.html
• http://jsonapi.org
• http://www.infoq.com/articles/Web-APIs-From-Start-to-Finish
• http://restfulwebapis.com
• http://www.restapitutorial.com
• http://martinfowler.com/articles/richardsonMaturityModel.html
• http://restcookbook.com
• http://www.w3.org/TR/json-ld/
• http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm
• http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
• http://brockallen.com/2012/05/14/http-status-codes-for-rest/
Thank you!
@endersonmaia