Machine Interfaces

technology

Machine interfaces for Sittercity

If everyone is busy making everything how can anyone perfect
anything? – Apple, 2013

RESTful interfaces (or RFC 2616 done properly)

Client – Server Stateless Cacheable Layered Uniformity

Client – Server Clients do not have implementation knowledge of
business rules or persistence Server is not concerned with state or presentation for humans Decouples components. Server and client implementations can be modiﬁed safely as long as the interface is maintained

Stateless Lack of state means the server can be replicated
quickly and easily – good for horizontal scalability Authentication and authorization must be provided with each request All information required to service the call must be passed with the request

Cacheable Clients can and should cache server responses based on
cache rules provided by the server Intermediate proxies can also cache responses with varying levels of complexity – see Varnish

Layered Clients are not concerned with where the response came
from. It could be the server or a proxy Allows for highly scalable architectures

Uniformity Identiﬁcation of resources through uniform resource identiﬁers Manipulation of
resources through representation Self-describing interactions HATEOAS – say what?

Methods

GET POST PUT DELETE HEAD TRACE OPTIONS CONNECT

What’s wrong with PUT?

Control through status codes

100 – 101 200 – 206 300 – 307 400
– 417 500 – 505 Informational Successful Redirection Client error (you ﬁx and try again) Server error (they ﬁx and try again)

just using 200 OK is not OK, m’kay!

200 OK 204 No Content 206 Partial Content 300 Multiple
Choices 301 Moved Permanently 302 Found 304 Not Modiﬁed 307 Temporary Redirect 400 Bad Request 401 Unauthorized 403 Forbidden 404 Not Found 405 Method Not Allowed 406 Not Acceptable 410 Gone 414 Request URI Too Large GET

201 Created 202 Accepted 204 No Content 205 Reset Content
303 See Other ! 400 Bad Request 401 Unauthorized 403 Forbidden 405 Method Not Allowed 406 Not Acceptable 411 Length Required 412 Precondition Failed 413 Request Entity Too Large 414 Request URI Too Large 415 Unsupported Media Type POST

201 Created 202 Accepted 204 No Content 205 Reset Content
400 Bad Request 401 Unauthorized 403 Forbidden 405 Method Not Allowed 406 Not Acceptable 409 Conﬂict 411 Length Required 412 Precondition Failed 413 Request Entity Too Large 414 Request URI Too Large 415 Unsupported Media Type PUT

200 OK 202 Accepted 204 No Content 205 Reset Content
400 Bad Request 401 Unauthorized 403 Forbidden 405 Method Not Allowed 414 Request URI Too Large DELETE

Content negotiation

What is the correct content type to serve?

Accept: application/json,text/html;q=0.9,*/*;q=0.8

Accept: text/html,application/xhtml+xml,application/ xml;q=0.9,image/webp,*/*;q=0.8

What the…?

HTTP/1.1 406 Not Acceptable Content-Type: text/html ! <html> <head><title>Not Acceptable</title></head>
<body> <h1>Not Acceptable</h1> <p>Acceptable content types</p> <ul> <li>text/html</li> <li>application/json</li> <li>application/xml</li> </ul> <body> </html>

Sittercity machine interfaces must support requests for JSON ! Should
support other sensible content types

Accept: application/json

HTTP/1.1 200 OK Content-Type: application/json Content-Length: 123 Cache-Control: public,proxy-revalidate ETag:
d34c0b44089aaa99ad359 ! { "com.sittercity.jobs:RateGuide": { "location": { "sittercity_location_id": 1234, "locality": "Charlotte, NC", "average_job_rate": { "unit": "hour", "currency": "USD", "mantissa": "-2", "value": "1000" } } } }

Hypermedia As The Engine Of Application State

Hypertext Application Language Resources have links to URIs, embedded resources,
and state Links have a target URI, relation (as in “rel”), other option properties

{ “_links”: { “self”: {“href”: “/jobs?offset=0&limit=10”}, “next”: {“href”: “/jobs?offset=10&limit=10”} }
}

Content-type: application/hal+json

HTTP/1.1 200 OK Content-Type: application/hal+json Content-Length: 123 Cache-Control: public,proxy-revalidate ETag:

Sittercity machine interfaces must support hypertext application language compatible JSON

Versioning by content type

Accept: application/hal+json;version=1

HTTP/1.1 200 OK Content-Type: application/hal+json;version=1 Content-Length: 123 Cache-Control: public,proxy-revalidate ETag:

Sittercity machine interfaces must manage interface versioning using content types
! Should serve the latest version if no content type is supplied

to Err is to be Human

providing good error messages is just polite

Errors should contain a human comprehensible message Recovery URIs allow
clients to provide options to escape the error Log references allow for machine parsing of error state

Content-type: application/vnd.error+json

{ "logref": 42, "message": "Validation failed", "_links": { "help": {
"href": "http://.../", "title": "Error Information" }, "describes": { "href": "http://.../", "title": "Error Description" } } }

Sittercity machine interfaces must error using valid vnd.error+json responses

Caching

Entity tags (ETag) provide a hash representation of resource Last-modiﬁed
headers can use updated_at attributes Both can be tested by client and supported by proxies and server with 304 Not Modiﬁed responses

Cache control headers provide rich rules for managing caching logic
at all layers

Sittercity machine interfaces should use cache control headers correctly

In summary

must manage interface versioning using content types ! should serve
the latest version if no content type version is supplied ! must support hypertext application language compatible JSON ! should support other sensible content types ! must error using valid vnd.error+json responses ! should use cache control headers correctly ! must enforce authorization using RFC 6749 & RFC 6750 Sittercity machine interfaces…

RFC 2616 HTTP http://tools.ietf.org/html/rfc2616 ! HAL http://tools.ietf.org/html/draft-kelly-json-hal-06  http://stateless.co/hal_speciﬁcation.html ! vnd.error
https://github.com/blongden/vnd.error ! RFC 5849 OAuth http://tools.ietf.org/html/rfc5849 RFC 6749 OAuth2 http://tools.ietf.org/html/rfc6749  RFC 6750 http://tools.ietf.org/html/rfc6750

Machine Interfaces

Machine Interfaces

More Decks by Sam de Freyssinet

Other Decks in Technology

Featured

Transcript