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