Spec First API Development With OpenAPI

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. Spec First API Development With OpenAPI and Friends 1/98 — VarnaConf 2019 | @specter_bg
2. So you need to build an API 2/98 — VarnaConf 2019 | @specter_bg
3. Where do you start? 3/98 — VarnaConf 2019 | @specter_bg
4. The Database? 4/98 — VarnaConf 2019 | @specter_bg
5. The Clients? 5/98 — VarnaConf 2019 | @specter_bg
6. The Code? 6/98 — VarnaConf 2019 | @specter_bg
7. What about docs? 7/98 — VarnaConf 2019 | @specter_bg
8. What about tests? 8/98 — VarnaConf 2019 | @specter_bg
9. What about validation? 9/98 — VarnaConf 2019 | @specter_bg
10. And now you need to change something 10/98 — VarnaConf 2019 | @specter_bg
11. Sounds familiar? 11/98 — VarnaConf 2019 | @specter_bg
12. GET /speakers/boyan → Boyan Yordanov → Ranting at @specter_bg → PHP Varna and VarnaJS organizer → VarnaLab member → Developer @ Shtrak 12/98 — VarnaConf 2019 | @specter_bg
13. So who likes writing documentation? 13/98 — VarnaConf 2019 | @specter_bg
14. Documentation that is: → "too long to read" → "totally useless" → "not updated" 14/98 — VarnaConf 2019 | @specter_bg
15. just boring 15/98 — VarnaConf 2019 | @specter_bg
16. API Specifications 16/98 — VarnaConf 2019 | @specter_bg
17. → machine readable → easy to write → more than documentation 17/98 — VarnaConf 2019 | @specter_bg
18. I still have to write it, though. — me 18/98 — VarnaConf 2019 | @specter_bg
19. I can do so much with it. — also me (a couple of months later) 19/98 — VarnaConf 2019 | @specter_bg
20. So why bother with an API specification? 20/98 — VarnaConf 2019 | @specter_bg
21. → Endpoints change or disappear. → Your client is out of date. → Parameters switch types. → Tests fail. You have to go on a quest ... again. 1 1 http://www.commitstrip.com 21/98 — VarnaConf 2019 | @specter_bg
22. 22/98 — VarnaConf 2019 | @specter_bg
23. 23/98 — VarnaConf 2019 | @specter_bg
24. Our process has failed us 24/98 — VarnaConf 2019 | @specter_bg
25. 1. little upfront design work 25/98 — VarnaConf 2019 | @specter_bg
26. 2. unannounced or miscommunicated changes 26/98 — VarnaConf 2019 | @specter_bg
27. waste 27/98 — VarnaConf 2019 | @specter_bg
28. frustration 28/98 — VarnaConf 2019 | @specter_bg
29. more meetings 29/98 — VarnaConf 2019 | @specter_bg
30. Common problems → changes aren't properly tested → clients constantly wait for the API → documentation and code don't match → SDKs have another opinion 30/98 — VarnaConf 2019 | @specter_bg
31. https://blog.apisyouwonthate.com/why-do-people-dislike-json- a7d67c8d38c1 31/98 — VarnaConf 2019 | @specter_bg
32. What can we do? 32/98 — VarnaConf 2019 | @specter_bg
33. 33/98 — VarnaConf 2019 | @specter_bg
34. Weeks of coding can save you hours of planning! — unknown 34/98 — VarnaConf 2019 | @specter_bg
35. Specification first 35/98 — VarnaConf 2019 | @specter_bg
36. Specifications as contracts 36/98 — VarnaConf 2019 | @specter_bg
37. Game plan 37/98 — VarnaConf 2019 | @specter_bg
38. 1. discuss the design 38/98 — VarnaConf 2019 | @specter_bg
39. 2. write the specification 39/98 — VarnaConf 2019 | @specter_bg
40. 3. generate docs and mock API 40/98 — VarnaConf 2019 | @specter_bg
41. 4. refine the specification 41/98 — VarnaConf 2019 | @specter_bg
42. 5. use it in tests 42/98 — VarnaConf 2019 | @specter_bg
43. 6. work on the code 43/98 — VarnaConf 2019 | @specter_bg
44. Benefits 1. single source of truth for our design 2. always up to date documentation and tests 3. work on backend and clients independently 44/98 — VarnaConf 2019 | @specter_bg
45. API Specification Formats 45/98 — VarnaConf 2019 | @specter_bg
46. 46/98 — VarnaConf 2019 | @specter_bg
47. API Blueprint → quite mature → markdown based → development is open on GitHub → mostly documentation oriented → tooling for the most essential things 47/98 — VarnaConf 2019 | @specter_bg
48. RAML → yaml based → covers the whole design/development process → syntax is quite similar to the OpenAPI Specification 48/98 — VarnaConf 2019 | @specter_bg
49. JSON Schema → json based → focused on the data model → great for validation and tests → has json-hyper-schema for hypermedia 49/98 — VarnaConf 2019 | @specter_bg
50. 50/98 — VarnaConf 2019 | @specter_bg
51. formerly known as Swagger 51/98 — VarnaConf 2019 | @specter_bg
52. formerly known as Swagger 52/98 — VarnaConf 2019 | @specter_bg
53. It's OpenAPI now 53/98 — VarnaConf 2019 | @specter_bg
54. About the spec → has lots of tools → yaml or json based → very active community → backed by companies and widely adopted 54/98 — VarnaConf 2019 | @specter_bg
55. OpenAPI Crash Course 55/98 — VarnaConf 2019 | @specter_bg
56. read the spec at https://spec.openapis.org/oas/v3.0.2 56/98 — VarnaConf 2019 | @specter_bg
57. Basic structure openapi: “3.0.0” info: # ... servers: # ... paths: # ... tags: # ... components: # ... 57/98 — VarnaConf 2019 | @specter_bg
58. Basic information about the API info: description: >- *Imaginary* API for managing meetups. Imagined for this **VarnaConf 2019** talk. version: '0.1' title: Meetups Are Awesome API contact: email: boyan.yordanov.dev@gmail.com name: Boyan Yordanov url: 'https://boyanyordanov.com' license: # ... 58/98 — VarnaConf 2019 | @specter_bg
59. 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 59/98 — VarnaConf 2019 | @specter_bg
60. What can the API do paths: /meetups # ... /meetups/{id} # ... /meetups/{id}/events # ... 60/98 — VarnaConf 2019 | @specter_bg
61. A path description /meetups: summary: meetups description: Meetups resource tags: # .. parameters: # .. get: # ... post: # .. 61/98 — VarnaConf 2019 | @specter_bg
62. Describing parameters /meetups: # ... parameters: - name: city in: query / path / header description: Filter meetups based on city schema: type: string 62/98 — VarnaConf 2019 | @specter_bg
63. 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 63/98 — VarnaConf 2019 | @specter_bg
64. Possible responses /meetups/{id} get: responses: '200': content: application/json: schema: # ... '404': content: application/problem+json: # ... 64/98 — VarnaConf 2019 | @specter_bg
65. Schema objects → based JSON Schema draft 4 witch some things added and some taken out → support references → in future might support current versions of JSON Schema and other formats 65/98 — VarnaConf 2019 | @specter_bg
66. example schema schema: type: object properties: id: type: string format: uuid name: type: string starting-date: type: string format: date 66/98 — VarnaConf 2019 | @specter_bg
67. nullable fields city: description: either a string or null type: string nullable: true 67/98 — VarnaConf 2019 | @specter_bg
68. other schema formats still a proposal 7 response: '200': content: application/json: x-oas-draft-alternativeSchema: type: jsonSchema location: ./real-jsonschema.json 7 https://github.com/stoplightio/spectral 68/98 — VarnaConf 2019 | @specter_bg
69. Reference object → object with $ref property → reference objects in the same document → reference external documents → replace inline definitions for most OpenAPI components 69/98 — VarnaConf 2019 | @specter_bg
70. Replace almost anything in the spec schema: $ref: '#/components/schemas/Meetup' # ... responses: '200': content: application/json: schema: $ref: 'MeetupsListResponse.yaml' 70/98 — VarnaConf 2019 | @specter_bg
71. Components components: schemas: # ... responses: # ... parameters: # ... requestBodies: # ... headers: # ... examples: # ... 71/98 — VarnaConf 2019 | @specter_bg
72. Tools 72/98 — VarnaConf 2019 | @specter_bg
73. Editors 73/98 — VarnaConf 2019 | @specter_bg
74. VSCode with openapi-lint extention → validates and lints → resloves external references → converts OpenAPI 2.0 to OpenAPI 3.0 → intellisense for both formats 74/98 — VarnaConf 2019 | @specter_bg
75. Swagger Editor 75/98 — VarnaConf 2019 | @specter_bg
76. Apicurio 76/98 — VarnaConf 2019 | @specter_bg
77. OpenAPI GUI 77/98 — VarnaConf 2019 | @specter_bg
78. Senya Editor 3 → PhpStorm (JetBrains) plugin → smart completion → live linting → handles $refs well → preview in Swagger UI ¯\_(ϑ)_/¯ → quite expensive 3 https://senya.io 78/98 — VarnaConf 2019 | @specter_bg
79. Linters 79/98 — VarnaConf 2019 | @specter_bg
80. Speccy 4 → lints your specification → supports rulesets → docs preview with ReDoc → resolve spec in one file → supports external references written in json- schema 4 https://github.com/wework/speccy 80/98 — VarnaConf 2019 | @specter_bg
81. Spectral 7 → based entirely on rulesets → lints OpenAPI 2/3 out of the box → extremely flexible 7 https://github.com/stoplightio/spectral 81/98 — VarnaConf 2019 | @specter_bg
82. Documentation 82/98 — VarnaConf 2019 | @specter_bg
83. Swagger UI - least favorite 83/98 — VarnaConf 2019 | @specter_bg
84. Widdershins + Slate / Shins.js 84/98 — VarnaConf 2019 | @specter_bg
85. ReDoc 85/98 — VarnaConf 2019 | @specter_bg
86. Mock Servers 86/98 — VarnaConf 2019 | @specter_bg
87. Stoplight.io / Prism 5 $ npm install -g @stoplight/prism-cli $ prism mock openapi.yml APISprout 6 $ docker pull danielgtaylor/apisprout $ docker run -p 8000:8000 danielgtaylor/apisprout openapi.yaml 6 https://github.com/danielgtaylor/apisprout 5 https://github.com/stoplightio/prism 87/98 — VarnaConf 2019 | @specter_bg
88. Testing 88/98 — VarnaConf 2019 | @specter_bg
89. Postman → import trough the app → import using the API 89/98 — VarnaConf 2019 | @specter_bg
90. OpenAPI <-> JSON Schema conversion https://github.com/mikunn/openapi2schema https://github.com/wework/json-schema-to- openapi-schema 90/98 — VarnaConf 2019 | @specter_bg
91. Why convert? best of both worlds (sort of) 91/98 — VarnaConf 2019 | @specter_bg
92. Example test 2 describe Api::MeetupsController, :type => :request do describe "GET /meetups" do it 'should return a list of meetups' do # ... get '/meetups' expect(response).to have_http_status(:success) expect(response).to match_json_schema("meetups") end end end 2 https://github.com/thoughtbot/json_matchers 92/98 — VarnaConf 2019 | @specter_bg
93. Code Generation 93/98 — VarnaConf 2019 | @specter_bg
94. OpenAPI Generator → community supported fork of swagger-codegen → supports OpenAPI 3.0 → Updated templates for different languages and frameworks 94/98 — VarnaConf 2019 | @specter_bg
95. openapi.tools thanks to Phil Sturgeon and Matthew Trask 95/98 — VarnaConf 2019 | @specter_bg
96. Thank you! 96/98 — VarnaConf 2019 | @specter_bg
97. Questions? 97/98 — VarnaConf 2019 | @specter_bg
98. Resources → Specification: https://swagger.io/specification → 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/ 98/98 — VarnaConf 2019 | @specter_bg