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. 10.

    YOU SOMEHOW MANAGE TO GET GOING AND PRODUCE SOMETHING WORKING

    10/92 — BulgariaPHP 2019 | @specter_bg
  2. 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
  3. 14.

    The backend developers said they can only return data from

    one table. — Mobile Developer 14/92 — BulgariaPHP 2019 | @specter_bg
  4. 15.

    The frontend devs want unrelated data. We'll just return everything.

    -- Backend Developers 15/92 — BulgariaPHP 2019 | @specter_bg
  5. 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
  6. 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
  7. 27.

    Weeks of coding can save you hours of planning! —

    unknown 27/92 — BulgariaPHP 2019 | @specter_bg
  8. 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
  9. 35.
  10. 36.

    CHOOSE THE RIGHT ONE FOR YOU > OpenAPI > RAML

    > API Blueprint 36/92 — BulgariaPHP 2019 | @specter_bg
  11. 41.

    ABOUT THE SPEC > has lots of tools > yaml

    or json based > very active community > widely adopted 41/92 — BulgariaPHP 2019 | @specter_bg
  12. 45.

    BASIC STRUCTURE openapi: “3.0.0” info: # ... servers: # ...

    paths: # ... tags: # ... components: # ... 45/92 — BulgariaPHP 2019 | @specter_bg
  13. 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
  14. 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
  15. 48.

    WHAT CAN THE API DO paths: /meetups # ... /meetups/{id}

    # ... /meetups/{id}/events # ... 48/92 — BulgariaPHP 2019 | @specter_bg
  16. 49.

    A path description /meetups: parameters: # .. get: # ...

    post: # .. delete: # .. 49/92 — BulgariaPHP 2019 | @specter_bg
  17. 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
  18. 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
  19. 52.

    OPERATIONS get: operationId: findMeetups summary: Find Meetups description: Find and

    search for meetups tags: - meetups parameters: # ,.. responses: # ... 52/92 — BulgariaPHP 2019 | @specter_bg
  20. 53.

    POSSIBLE RESPONSES /meetups/{id} get: responses: '200': content: application/json: schema: #

    ... '404': content: application/problem+json: # ... 53/92 — BulgariaPHP 2019 | @specter_bg
  21. 54.

    HEADERS headers: RateLimit-Limit: description: The number of allowed requests in

    the current period schema: type: integer 54/92 — BulgariaPHP 2019 | @specter_bg
  22. 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
  23. 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
  24. 57.

    NULLABLE FIELDS city: description: either a string or null type:

    string nullable: true 57/92 — BulgariaPHP 2019 | @specter_bg
  25. 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
  26. 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
  27. 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
  28. 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
  29. 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
  30. 68.

    OPTIONS > ReDoc > Swagger UI (hosted option) > Stoplight

    Hosted 68/92 — BulgariaPHP 2019 | @specter_bg
  31. 72.

    OPTIONS > Prism > API Sprout > SwaggerHub > Roll

    your own 72/92 — BulgariaPHP 2019 | @specter_bg
  32. 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
  33. 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
  34. 78.

    OPENAPI-GENERATOR > generate server stubs > generate clients > custom

    generators > some generators might be out of date 78/92 — BulgariaPHP 2019 | @specter_bg
  35. 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
  36. 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
  37. 84.

    POSTMAN > Direct OpenAPI import trough GUI > Import with

    Postman API 84/92 — BulgariaPHP 2019 | @specter_bg
  38. 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
  39. 87.

    IF YOU NEED MORE TOOLS OPENAPI.TOOLS! SAY THANKS TO MATT

    TRASK AND PHIL STURGEON! 87/92 — BulgariaPHP 2019 | @specter_bg
  40. 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