Self Discovery in APIs

Slides for my talk about extending your APIs making them self-discoverable and self-documenting. Main topics include HATEOAS and JSON-Schema

Transcript

1. Self Discovery in (RESTful) APIs by Vladimir Hraban
2. REST is self-descriptive • URL maps to the resource • HTTP verbs describe the action that can be performed on the resource • Status codes describe the request outcome • Request type (or pseudo format in the URL) asks for a particular data representation in the response
3. Request: GET /accounts Response: 200 OK Collection
4. Request: GET /accounts/1234 Response: 200 OK Request: PUT /accounts/1234 Response: 200 OK Item
5. Isn’t it already perfect? • Client needs to know about resources available • If we get all the collection, the response can contain thousands of resources. Pagination means some custom API logic, and the client needs to be aware of it • Returned response does not have to include all children resources even though they may exist. Client needs to know about relationships between resources • If the URI changes, client needs to be updated accordingly • … • In summary: client needs to know a lot about the API on order to consume it, and most API changes require a client update It is NOT enough
6. HATEOAS • Hypermedia As The Engine of Application State • Client has no prior knowledge on how to interact with the server • Can be easily parsed by the client • Client traverses the response to get deeper into the resource relationships • API can drive the state of the application
7. In action Our API did not tell us anything about the account. Which is correct, we only requested the account details. With HATEOAS hyperlinks can and should be included in the response
8. In action • The client now knows that each account has subscriptions and preferences, and knows the URIs to access them • Combined with REST RFC knowledge, the consumer can now retrieve account preferences, get current subscriptions or update them
9. How does it drive the application state? This is how a subscription can be renewed GET /accounts/1234/subscriptions/1234567 Response:
10. How does it drive the application state? But if according to some business rules renewal is not possible, our API response can easily reflect that GET /accounts/1234/subscriptions/1234567
11. URIs can change without client update The client can access resources URIs by extracting href attribute of the corresponding rel Therefore URIs can change, relationships can be swapped and the whole API structure can change without the need to update the client As long as the client does not access URIs by direct URL and uses rel/href pair instead
12. But what about resource schema? Assuming the client now needs to add a new resource of a type subscription to the given account, how does it know what data to send? JSON-Schema http://json-schema.org/latest/json-schema- hypermedia.html Note: There is no standard defining where JSON-Schema should go in RESTful APIs
13. JSON Reference This is achieved by adding a $ref key JSON Reference defines a way to reference an external JSON Schema https://tools.ietf.org/id/draft-pbryan-zyp-json-ref-03.html
14. Why not include the definition into the resource that schema is describing with the help of JSON reference
15. GET /definitions/renewal http://json-schema.org/examples.html
16. Summary • HATEOAS is quick and easy solution to quickly introduce self-discovery into APIs • Self-documenting resource schema may be a pain but it will pay off in the future • There are a lot of missing or not-so-popular standards and that makes this self discovery movement much more problematic • Some good tendencies are in place, and the following are the proof: • https://developer.github.com/v3/ • Spring-Hateoas package for Java Spring Framework • In Python world there is REST Django framework built-in self-discovery • http://micro-api.org/ • http://jsonapi.org/ • https://developers.google.com/discovery/ • Nice libraries exist to automatically validate and parse JSON schema
17. Thank you ☺