Design First APIs with OpenAPI - BG PHP 19

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.

807dcecdfca0e4078d89127cd440c039?s=128

Boyan Yordanov

November 09, 2019
Tweet

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