Pragmatic Web API Design

Presented at Z1 Data

Transcript

1. Pragmatic Web API Design Samnang Chhun | @samnangchhun
2. API Design Table of Contents Basics of HTTP 1 3 JSON:API 4 Discussion 2
3. Basics of HTTP HTTP is the foundation of data communication for the World Wide Web
4. HTTP Application Layer Protocol ✽ Client - Server Model ✽ Decoupled ✽ Stateless ✽ Extensible ✽
5. HTTP Request Message URI ✽ Method ✽ Headers ✽ Message Body (optional) ✽
6. HTTP Response Message Response Code ✽ Headers ✽ Message Body (optional) ✽
7. API Design
8. Modeling APIs Your API Is a Contract
9. Modeling APIs Who Will Be Using Your API?
10. Modeling APIs What’s the Purpose of Your API?
11. Design guidelines Preventing migration of business logic to API consumer
12. Design guidelines An API is only as good as its documentation
13. Design guidelines Your resources are not your database tables
14. Design guidelines Use HTTP Status Codes
15. Design guidelines Use HTTP Methods
16. Design guidelines Define a consumable error payload
17. Design guidelines Adopt a hypermedia type for your API HAL ✽ Collection+JSON ✽ JSON:API SIREN ✽ ✽ Others ✽
18. A SPECIFICATION FOR BUILDING APIS IN JSON
19. Why JSON:API? The spec provides consistent rules for how requests and responses are formatted. ✽ • It reduces both the number of requests and the amount of data transmitted between clients and servers. ✽ • Following shared conventions, you can increase productivity, take advantage of generalized tooling, and focus on what matters: your application. ✽ • Strong ecosystem in developer community. ✽
20. JSON:API It’s a Standard ✅
21. A document MAY contain any of these top-level members: Top Level Document Structure data: the document’s “primary data” ✽ errors: an array of error objects ✽ meta: a meta object that contains non-standard meta-information. ✽ jsonapi: an object describing the server’s implementation. ✽ links: a links object related to the primary data. ✽ included: an array of resource objects that are related to the primary data and/or each other (“included resources”). ✽ A document MUST contain at least one of the following top-level members:
22. A resource object MUST contain at least the following top-level members: Resource Objects id: the document’s “primary data” ✽ type: an array of error objects ✽ In addition, a resource object MAY contain any of these top-level members: attributes: an attributes object representing some of the resource’s data ✽ relationships: a relationships object describing relationships between the resource and other JSON:API resources. ✽ meta: a meta object containing non-standard meta-information about a resource that can not be represented as an attribute or relationship. links: a links object containing links related to the resource. ✽ ✽
23. Resource Objects (Example)
24. Compound Documents
25. Sparse Fieldsets A client MAY request that an endpoint return only specific fields in the response on a per-type basis by including a field[TYPE] parameter.
26. Sorting A server MAY choose to support requests to sort resource collections according to one or more criteria (“sort fields”).
27. Pagination A server MAY choose to limit the number of resources returned in a response to a subset (“page”) of the whole set available. The following keys MUST be used for pagination links: first: the first page of data ✽ last: the last page of data ✽ next: the next page of data prev: the previous page of data ✽ ✽
28. Filtering The filter query parameter is reserved for filtering data. Servers and clients SHOULD use this key for filtering operations.
29. Error Object Error objects MUST be returned as an array keyed by errors in the top level of a JSON:API document.
30. Asynchronous Processing Consider a situation when you need to create a resource and the operation takes a long time to complete.
31. Adopted Implementations
32. Thank You
33. Discussions
34. The Clean Architecture
35. Request / Response