Creating Solid APIs - PyCon Estonia 2018

Presented at PyCon Estonia 2018

Creating APIs that other developers love to use isn't trivial. I'll share some tips and best practices.

See also: https://rivolaks.com/posts/creating-solid-apis/

Transcript

1. Creating Solid APIs PyCon Estonia 2018 Rivo Laks ⋅ 2018-10-04
2. Background
3. What is an API?
4. What is an API? application programming interface
5. What is an API? application programming interface application programmer interface
6. What is an API? application programming interface application programmer interface API is user interface for developers
7. Goals
8. Goals
9. Goals Comprehensive API for 3rd-party devs
10. Goals Comprehensive API for 3rd-party devs Easy & automated onboarding
11. Goals Comprehensive API for 3rd-party devs Easy & automated onboarding Minimize pain (friction)
12. Versioning
13. Why Do We Need Versioning?
14. Why Do We Need Versioning? for breaking things in controlled fashion
15. How to Version?
16. How to Version? You need: Deprecation schedules
17. How to Version? You need: Deprecation schedules Changelogs / upgrade notes
18. Versioning Schemes
19. Versioning Schemes Using Accept header GET /projects HTTP/1.0 Accept: application/json; version=1
20. Versioning Schemes Using Accept header GET /projects HTTP/1.0 Accept: application/json; version=1 Using URL path GET /v1/projects HTTP/1.0 Accept: application/json
21. Versioning Schemes Cont. Integers ( v1 ) vs dates ( 2018-10-04 )?
22. Versioning Schemes Cont. Integers ( v1 ) vs dates ( 2018-10-04 )? Dates are less emotional
23. Versioning Schemes Cont. Integers ( v1 ) vs dates ( 2018-10-04 )? Dates are less emotional Easier internal / test versions
24. Version Transformers
25. Version Transformers » » Requests into newer version » » Core code is for latest version « « Responses into older version « «
26. Version Transformers » » Requests into newer version » » Core code is for latest version « « Responses into older version « « Won't work for big, breaking changes
27. Authentication & Authorization
28. Token Authentication Clients send HTTP header, ala Authorization: Token 9944b09199c62bcf9418
29. OAuth 2.0
30. OAuth 2.0 For creating platforms
31. OAuth 2.0 For creating platforms Complex, but solves many issues
32. OAuth 2.0 For creating platforms Complex, but solves many issues Many packages, e.g. Django OAuth Toolkit, OAuthLib
33. Standardize!
34. Standardize! Standards help: bring familiarity
35. Standardize! Standards help: bring familiarity avoid common pitfalls
36. Standardize! Standards help: bring familiarity avoid common pitfalls historically, standardized approaches win
37. JSON API http://jsonapi.org/ one potential standard to use
38. JSON API http://jsonapi.org/ one potential standard to use GraphQL is another option
39. Standardize Structure
40. Standardize Structure Responses have predictable, familiar structure
41. GET https://example.com/api/v1/projects { "links": { "next": "https://example.com/api/v1/projects?cursor=cD0yMDE4L", "prev": null }, "data": [...], "included": [...] }
42. "data": [ { "type": "project", "id": "289", "links": { "self": "https://example.com/api/v1/projects/289" }, "attributes": { "created": "2018-06-28T22:52:08.690486Z", "name": "Allison-Patterson", "description": "aggregate collaborative models" }, "relationships": {...} }, ... ],
43. "data": [{ ... "relationships": { "created_by": { "data": { "type": "user", "id": "199" } }, "epics": { "data": [ { "type": "epic", "id": "3101" } ], } } }, ... ],
44. "included": [ { "type": "epic", "id": "3101", "attributes": { "created": "2018-06-28T22:50:45.885691Z", "name": "Ergonomic background extranet" }, "links": { "self": "https://example.com/api/v1/epics/3101" } }, { "type": "user", "id": "199", "attributes": {...} } ]
45. Impressions?
46. Flexibility Con gurable elds: GET https://example.com/api/v1/projects GET https://example.com/api/v1/projects \ ?included=comments GET https://example.com/api/v1/projects \ ?included=comments&fields[project]=name,comments
47. Errors
48. Errors POST https://example.com/api/v1/projects { "errors": [ { "title": "Invalid Attribute", "detail": "Name must contain at least three letters.", "source": { "pointer": "/data/attributes/name" }, "code": "name_too_short", "status": "422" } ] }
49. Standardization Matters the speci c standard isn't that important GraphQL, etc are also good options
50. Documentation
51. Documentation Often overlooked
52. Documentation Often overlooked Gives the rst impression
53. Documentation Often overlooked Gives the rst impression The e ort is worth it!
54. Creating Awesome Docs
55. What Should Go In There?
56. What Should Go In There? The purpose
57. What Should Go In There? The purpose How do I access it?
58. What Should Go In There? The purpose How do I access it? Do I need developer account?
59. What Should Go In There? The purpose How do I access it? Do I need developer account? Root URL, etc
60. What Should Go In There? The purpose How do I access it? Do I need developer account? Root URL, etc Authentication info
61. What Should Go In There? General encodings, formats, etc
62. What Should Go In There? General encodings, formats, etc Versioning, pagination, etc
63. What Should Go In There? General encodings, formats, etc Versioning, pagination, etc Common errors
64. What Should Go In There? General encodings, formats, etc Versioning, pagination, etc Common errors Code for getting started
65. The Endpoints
66. The Endpoints URL & operations
67. The Endpoints URL & operations Request/response data
68. The Endpoints URL & operations Request/response data Optional parameters
69. The Endpoints URL & operations Request/response data Optional parameters Permissions etc
70. Keep it Fresh!
71. Keep it Fresh! Obsolete docs are the worst
72. Keep it Fresh! Obsolete docs are the worst Always autogenerate!
73. Keep it Fresh! Obsolete docs are the worst Always autogenerate! Usually code » schema » docs
74. Schema & Autogeneration
75. Schema & Autogeneration OpenAPI, Swagger, etc
76. Schema & Autogeneration OpenAPI, Swagger, etc Use your tools
77. Schema & Autogeneration OpenAPI, Swagger, etc Use your tools Combine docs & code examples
78. Schema & Autogeneration OpenAPI, Swagger, etc Use your tools Combine docs & code examples Client libs autogeneration
79. In Summary Embrace standards (e.g. JSON API) Invest in documentation Use automation Reduce friction
80. Thanks! Rivo Laks ⋅ @rivolaks ⋅ rivolaks.com tinyurl.com/PyConEstonia18api