Design First APIs with OpenAPI - BG PHP 19

Imagine a world where the mobile development team is not constantly surprised by changing endpoints, where frontend developers don’t abuse your carefully crafted APIs and we don’t have to go back again and again to fix or change stuff. In this imaginary land we are able to leave the guesswork out by using API definitions to produce even better designs and automate parts of the process. Together we will explore OpenAPI as a standard way to describe APIs and see how it can help us get there.

Transcript

1. DESIGN FIRST APIS WITH OPENAPI AND FRIENDS 1/92 — BulgariaPHP 2019 | @specter_bg
2. SO YOU NEED TO BUILD AN API 2/92 — BulgariaPHP 2019 | @specter_bg
3. WHERE DO YOU START? 3/92 — BulgariaPHP 2019 | @specter_bg
4. THE DATABASE? 4/92 — BulgariaPHP 2019 | @specter_bg
5. THE CLIENTS? 5/92 — BulgariaPHP 2019 | @specter_bg
6. THE CODE? 6/92 — BulgariaPHP 2019 | @specter_bg
7. WHAT ABOUT DOCS? 7/92 — BulgariaPHP 2019 | @specter_bg
8. WHAT ABOUT TESTS? 8/92 — BulgariaPHP 2019 | @specter_bg
9. WHAT ABOUT VALIDATION? 9/92 — BulgariaPHP 2019 | @specter_bg
10. YOU SOMEHOW MANAGE TO GET GOING AND PRODUCE SOMETHING WORKING 10/92 — BulgariaPHP 2019 | @specter_bg
11. BUT NOW YOU NEED TO CHANGE SOMETHING 11/92 — BulgariaPHP 2019 | @specter_bg
12. SOUNDS FAMILIAR? 12/92 — BulgariaPHP 2019 | @specter_bg
13. GET /SPEAKERS/BOYAN > Boyan Yordanov > Ranting at @specter_bg > PHP Varna and VarnaJS organizer > VarnaLab member > always at the NomadPHP meetups 13/92 — BulgariaPHP 2019 | @specter_bg
14. The backend developers said they can only return data from one table. — Mobile Developer 14/92 — BulgariaPHP 2019 | @specter_bg
15. The frontend devs want unrelated data. We'll just return everything. -- Backend Developers 15/92 — BulgariaPHP 2019 | @specter_bg
16. This response is so bloated, we don’t need half of the data. Let’s just use GraphQL. — Front-end / Mobile Developers 16/92 — BulgariaPHP 2019 | @specter_bg
17. 17/92 — BulgariaPHP 2019 | @specter_bg
18. COMMON PROBLEMS 18/92 — BulgariaPHP 2019 | @specter_bg
19. > Endpoints change or disappear > Clients are out of date > Parameters switch types > clients constantly wait for the API > documentation and code don't match 19/92 — BulgariaPHP 2019 | @specter_bg
20. OUR PROCESS HAS FAILED US 20/92 — BulgariaPHP 2019 | @specter_bg
21. 1. LITTLE UPFRONT DESIGN WORK 21/92 — BulgariaPHP 2019 | @specter_bg
22. 2. UNANNOUNCED OR MISCOMMUNICATED CHANGES 22/92 — BulgariaPHP 2019 | @specter_bg
23. WASTE 23/92 — BulgariaPHP 2019 | @specter_bg
24. FRUSTRATION 24/92 — BulgariaPHP 2019 | @specter_bg
25. MORE MEETINGS 25/92 — BulgariaPHP 2019 | @specter_bg
26. WHAT CAN WE DO? 26/92 — BulgariaPHP 2019 | @specter_bg
27. Weeks of coding can save you hours of planning! — unknown 27/92 — BulgariaPHP 2019 | @specter_bg
28. THE PROCESS 2 1. Plan / Design 2. Gather feedback 3. Improve the design 4. Implement the code 5. Verify the implementation 2 Learn more: apisyouwonthate.com/blog/api-design-first-vs-code-first 28/92 — BulgariaPHP 2019 | @specter_bg
29. ITERATE 29/92 — BulgariaPHP 2019 | @specter_bg
30. DESIGN IS NOT A ONE TIME EVENT. 30/92 — BulgariaPHP 2019 | @specter_bg
31. REPEAT THE PROCESS FOR EVERY CHANGE. 31/92 — BulgariaPHP 2019 | @specter_bg
32. PLANNING / DESIGN 32/92 — BulgariaPHP 2019 | @specter_bg
33. 33/92 — BulgariaPHP 2019 | @specter_bg
34. API SPECIFICATIONS 34/92 — BulgariaPHP 2019 | @specter_bg
35. A CONTRACT BETWEEN THE API AND ITS USERS 35/92 — BulgariaPHP 2019 | @specter_bg
36. CHOOSE THE RIGHT ONE FOR YOU > OpenAPI > RAML > API Blueprint 36/92 — BulgariaPHP 2019 | @specter_bg
37. 37/92 — BulgariaPHP 2019 | @specter_bg
38. FORMERLY KNOWN AS SWAGGER 38/92 — BulgariaPHP 2019 | @specter_bg
39. FORMERLY KNOWN AS SWAGGER 39/92 — BulgariaPHP 2019 | @specter_bg
40. OpenAPI 40/92 — BulgariaPHP 2019 | @specter_bg
41. ABOUT THE SPEC > has lots of tools > yaml or json based > very active community > widely adopted 41/92 — BulgariaPHP 2019 | @specter_bg
42. WRITE BY HAND OR USE A GUI? 42/92 — BulgariaPHP 2019 | @specter_bg
43. OPENAPI CRASH COURSE 43/92 — BulgariaPHP 2019 | @specter_bg
44. READ THE SPEC AT HTTPS://SPEC.OPENAPIS.ORG/OAS/V3.0.2 44/92 — BulgariaPHP 2019 | @specter_bg
45. BASIC STRUCTURE openapi: “3.0.0” info: # ... servers: # ... paths: # ... tags: # ... components: # ... 45/92 — BulgariaPHP 2019 | @specter_bg
46. BASIC INFORMATION ABOUT THE API info: description: >- *Imaginary* free API for managing meetups. Imagined for this **BG PHP 2019** talk. version: '0.1' title: Not The Meetup API contact: email: boyan.yordanov.dev@gmail.com name: Boyan Yordanov url: 'https://boyanyordanov.com' license: # ... 46/92 — BulgariaPHP 2019 | @specter_bg
47. HOW CAN USERS ACCESS THE API servers: - url: 'https://imaginary-meetups.com/api' description: Imaginary API for managing Meetups - url: 'https://staging.imaginary-meetups.com/api' description: Staging server for the imaginary API - url: 'http://localhost:8080' description: Development version of the API 47/92 — BulgariaPHP 2019 | @specter_bg
48. WHAT CAN THE API DO paths: /meetups # ... /meetups/{id} # ... /meetups/{id}/events # ... 48/92 — BulgariaPHP 2019 | @specter_bg
49. A path description /meetups: parameters: # .. get: # ... post: # .. delete: # .. 49/92 — BulgariaPHP 2019 | @specter_bg
50. DESCRIBING PARAMETERS /meetups: # ... parameters: - name: city in: query / path / header / cookie description: Filter meetups based on city schema: type: string 50/92 — BulgariaPHP 2019 | @specter_bg
51. handling array parameters /meetups: # ... parameters: - name: technologies in: query description: Filter meetups based on city schema: type: array items: type: string style: form explode: false 51/92 — BulgariaPHP 2019 | @specter_bg
52. OPERATIONS get: operationId: findMeetups summary: Find Meetups description: Find and search for meetups tags: - meetups parameters: # ,.. responses: # ... 52/92 — BulgariaPHP 2019 | @specter_bg
53. POSSIBLE RESPONSES /meetups/{id} get: responses: '200': content: application/json: schema: # ... '404': content: application/problem+json: # ... 53/92 — BulgariaPHP 2019 | @specter_bg
54. HEADERS headers: RateLimit-Limit: description: The number of allowed requests in the current period schema: type: integer 54/92 — BulgariaPHP 2019 | @specter_bg
55. SCHEMA OBJECTS > based on JSON-Schema draft 4 with some things added and some taken out > support references 55/92 — BulgariaPHP 2019 | @specter_bg
56. EXAMPLE SCHEMA schema: type: object properties: id: type: string format: uuid name: type: string starting-date: type: string format: date 56/92 — BulgariaPHP 2019 | @specter_bg
57. NULLABLE FIELDS city: description: either a string or null type: string nullable: true 57/92 — BulgariaPHP 2019 | @specter_bg
58. OTHER FEATURES > Security schemes > callbacks (and webhooks hopefully soon) 3 > Links (design time only) 3 apisyouwonthate.com/blog/openapi-callbacks-and-webhooks 58/92 — BulgariaPHP 2019 | @specter_bg
59. OPENAPI 3.1 59/92 — BulgariaPHP 2019 | @specter_bg
60. EDITORS WHAT TO LOOK FOR > it should understand YAML > validate the spec > provide some auto-complete > docs preview (not essential) 60/92 — BulgariaPHP 2019 | @specter_bg
61. OPTIONS > Anything with YAML syntax highlighting > Visual Studio Code with openapi-lint extension ❤ > IntelliJ IDE + Senya editor (paid) > Swagger Editor 61/92 — BulgariaPHP 2019 | @specter_bg
62. GUI EDITORS 62/92 — BulgariaPHP 2019 | @specter_bg
63. WHY? > no need to fully understand the spec > can be faster to work > can be used by non-developers 63/92 — BulgariaPHP 2019 | @specter_bg
64. STOPLIGHT STUDIO 4 > Fully supports OAS 2 and 3 > Integrated linting via Spectral > Integrated mock server - Prism > Git integration > Docs including Markdown files 4 BeachCasts Video about Studio: youtube.com/watch?v=ZgYh7HwTJDE 64/92 — BulgariaPHP 2019 | @specter_bg
65. 65/92 — BulgariaPHP 2019 | @specter_bg
66. GATHER FEEDBACK 66/92 — BulgariaPHP 2019 | @specter_bg
67. DOCUMENTATION 67/92 — BulgariaPHP 2019 | @specter_bg
68. OPTIONS > ReDoc > Swagger UI (hosted option) > Stoplight Hosted 68/92 — BulgariaPHP 2019 | @specter_bg
69. 69/92 — BulgariaPHP 2019 | @specter_bg
70. MOCK API GATHER FEEDBACK 70/92 — BulgariaPHP 2019 | @specter_bg
71. 71/92 — BulgariaPHP 2019 | @specter_bg
72. OPTIONS > Prism > API Sprout > SwaggerHub > Roll your own 72/92 — BulgariaPHP 2019 | @specter_bg
73. PRISM > npm install -g @stoplight/prism-cli` > prism mock -d openapi.yaml { "data": { "id": "d8bb3694-9bee-434c-ce95-c9b368a87387", "name": "PHP Varna", "city": "Jenkinsmouth", "starting-date": "1982-04-21", "country": "Panama" } } 73/92 — BulgariaPHP 2019 | @specter_bg
74. IMPROVE THE DESIGN 74/92 — BulgariaPHP 2019 | @specter_bg
75. > Keep the spec in version control > Lint it in CI > Review changes in PRs > Regenerate docs, mocks server, tests 75/92 — BulgariaPHP 2019 | @specter_bg
76. IMPLEMENTATION 76/92 — BulgariaPHP 2019 | @specter_bg
77. CODE GENERATION 77/92 — BulgariaPHP 2019 | @specter_bg
78. OPENAPI-GENERATOR > generate server stubs > generate clients > custom generators > some generators might be out of date 78/92 — BulgariaPHP 2019 | @specter_bg
79. JANE PHP > generates better php clients > supports OpenAPI v3 and json-schema > based on PSR-7 and PSR-18 79/92 — BulgariaPHP 2019 | @specter_bg
80. VALIDATION 80/92 — BulgariaPHP 2019 | @specter_bg
81. THEPHPLEAGUE/OPENAPI-PSR7-VALIDATOR > new package from the PHP League > PSR-7 requests and response validation > PSR-15 middleware 81/92 — BulgariaPHP 2019 | @specter_bg
82. TESTING 82/92 — BulgariaPHP 2019 | @specter_bg
83. MANUAL TESTING 83/92 — BulgariaPHP 2019 | @specter_bg
84. POSTMAN > Direct OpenAPI import trough GUI > Import with Postman API 84/92 — BulgariaPHP 2019 | @specter_bg
85. AUTOMATED TESTS 85/92 — BulgariaPHP 2019 | @specter_bg
86. ROLL YOUR OWN ENHANCE YOUR FUNCTIONAL/INTEGRATION TESTS > extract response schemas from the spec > make a request > validate the response with a validation library 86/92 — BulgariaPHP 2019 | @specter_bg
87. IF YOU NEED MORE TOOLS OPENAPI.TOOLS! SAY THANKS TO MATT TRASK AND PHIL STURGEON! 87/92 — BulgariaPHP 2019 | @specter_bg
88. REPEAT 88/92 — BulgariaPHP 2019 | @specter_bg
89. BUILD SOMETHING AWESOME 89/92 — BulgariaPHP 2019 | @specter_bg
90. THANK YOU! 90/92 — BulgariaPHP 2019 | @specter_bg
91. QUESTIONS? 91/92 — BulgariaPHP 2019 | @specter_bg
92. RESOURCES > Specification: spec.openapis.org/oas/v3.0.2 > https://github.com/OAI/OpenAPI-Specification - issues / PRs > https://apisyouwonthate.com - books/blog/slack > https://philsturgeon.uk > https://apihandyman.io > https://apievangelist.com > http://json-schema.org > http://www.commitstrip.com/en/2018/02/26/its-good-to-have-experience/ 92/92 — BulgariaPHP 2019 | @specter_bg