Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Spec First API Development With OpenAPI

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.

Boyan Yordanov

June 15, 2019
Tweet

More Decks by Boyan Yordanov

Other Decks in Technology

Transcript

  1. Spec First API
    Development With
    OpenAPI and Friends
    1/98 — VarnaConf 2019 | @specter_bg

    View Slide

  2. So you need to build
    an API
    2/98 — VarnaConf 2019 | @specter_bg

    View Slide

  3. Where do you
    start?
    3/98 — VarnaConf 2019 | @specter_bg

    View Slide

  4. The Database?
    4/98 — VarnaConf 2019 | @specter_bg

    View Slide

  5. The Clients?
    5/98 — VarnaConf 2019 | @specter_bg

    View Slide

  6. The Code?
    6/98 — VarnaConf 2019 | @specter_bg

    View Slide

  7. What about docs?
    7/98 — VarnaConf 2019 | @specter_bg

    View Slide

  8. What about tests?
    8/98 — VarnaConf 2019 | @specter_bg

    View Slide

  9. What about validation?
    9/98 — VarnaConf 2019 | @specter_bg

    View Slide

  10. And now you need to
    change something
    10/98 — VarnaConf 2019 | @specter_bg

    View Slide

  11. Sounds familiar?
    11/98 — VarnaConf 2019 | @specter_bg

    View Slide

  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

    View Slide

  13. So who likes writing
    documentation?
    13/98 — VarnaConf 2019 | @specter_bg

    View Slide

  14. Documentation that is:
    → "too long to read"
    → "totally useless"
    → "not updated"
    14/98 — VarnaConf 2019 | @specter_bg

    View Slide

  15. just boring
    15/98 — VarnaConf 2019 | @specter_bg

    View Slide

  16. API Specifications
    16/98 — VarnaConf 2019 | @specter_bg

    View Slide

  17. → machine readable
    → easy to write
    → more than documentation
    17/98 — VarnaConf 2019 | @specter_bg

    View Slide

  18. I still have to write it,
    though.
    — me
    18/98 — VarnaConf 2019 | @specter_bg

    View Slide

  19. I can do so much with it.
    — also me (a couple of months later)
    19/98 — VarnaConf 2019 | @specter_bg

    View Slide

  20. So why bother with an
    API specification?
    20/98 — VarnaConf 2019 | @specter_bg

    View Slide

  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

    View Slide

  22. 22/98 — VarnaConf 2019 | @specter_bg

    View Slide

  23. 23/98 — VarnaConf 2019 | @specter_bg

    View Slide

  24. Our process
    has failed us
    24/98 — VarnaConf 2019 | @specter_bg

    View Slide

  25. 1. little upfront design
    work
    25/98 — VarnaConf 2019 | @specter_bg

    View Slide

  26. 2. unannounced or
    miscommunicated
    changes
    26/98 — VarnaConf 2019 | @specter_bg

    View Slide

  27. waste
    27/98 — VarnaConf 2019 | @specter_bg

    View Slide

  28. frustration
    28/98 — VarnaConf 2019 | @specter_bg

    View Slide

  29. more meetings
    29/98 — VarnaConf 2019 | @specter_bg

    View Slide

  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

    View Slide

  31. https://blog.apisyouwonthate.com/why-do-people-dislike-json-
    a7d67c8d38c1
    31/98 — VarnaConf 2019 | @specter_bg

    View Slide

  32. What can we
    do?
    32/98 — VarnaConf 2019 | @specter_bg

    View Slide

  33. 33/98 — VarnaConf 2019 | @specter_bg

    View Slide

  34. Weeks of coding can save
    you hours of planning!
    — unknown
    34/98 — VarnaConf 2019 | @specter_bg

    View Slide

  35. Specification
    first
    35/98 — VarnaConf 2019 | @specter_bg

    View Slide

  36. Specifications
    as contracts
    36/98 — VarnaConf 2019 | @specter_bg

    View Slide

  37. Game plan
    37/98 — VarnaConf 2019 | @specter_bg

    View Slide

  38. 1. discuss the design
    38/98 — VarnaConf 2019 | @specter_bg

    View Slide

  39. 2. write the specification
    39/98 — VarnaConf 2019 | @specter_bg

    View Slide

  40. 3. generate docs and mock API
    40/98 — VarnaConf 2019 | @specter_bg

    View Slide

  41. 4. refine the specification
    41/98 — VarnaConf 2019 | @specter_bg

    View Slide

  42. 5. use it in tests
    42/98 — VarnaConf 2019 | @specter_bg

    View Slide

  43. 6. work on the code
    43/98 — VarnaConf 2019 | @specter_bg

    View Slide

  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

    View Slide

  45. API Specification Formats
    45/98 — VarnaConf 2019 | @specter_bg

    View Slide

  46. 46/98 — VarnaConf 2019 | @specter_bg

    View Slide

  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

    View Slide

  48. RAML
    → yaml based
    → covers the whole design/development process
    → syntax is quite similar to the OpenAPI
    Specification
    48/98 — VarnaConf 2019 | @specter_bg

    View Slide

  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

    View Slide

  50. 50/98 — VarnaConf 2019 | @specter_bg

    View Slide

  51. formerly known as
    Swagger
    51/98 — VarnaConf 2019 | @specter_bg

    View Slide

  52. formerly known as
    Swagger
    52/98 — VarnaConf 2019 | @specter_bg

    View Slide

  53. It's OpenAPI
    now
    53/98 — VarnaConf 2019 | @specter_bg

    View Slide

  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

    View Slide

  55. OpenAPI
    Crash Course
    55/98 — VarnaConf 2019 | @specter_bg

    View Slide

  56. read the spec
    at https://spec.openapis.org/oas/v3.0.2
    56/98 — VarnaConf 2019 | @specter_bg

    View Slide

  57. Basic structure
    openapi: “3.0.0”
    info:
    # ...
    servers:
    # ...
    paths:
    # ...
    tags:
    # ...
    components:
    # ...
    57/98 — VarnaConf 2019 | @specter_bg

    View Slide

  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: [email protected]
    name: Boyan Yordanov
    url: 'https://boyanyordanov.com'
    license:
    # ...
    58/98 — VarnaConf 2019 | @specter_bg

    View Slide

  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

    View Slide

  60. What can the API do
    paths:
    /meetups
    # ...
    /meetups/{id}
    # ...
    /meetups/{id}/events
    # ...
    60/98 — VarnaConf 2019 | @specter_bg

    View Slide

  61. A path description
    /meetups:
    summary: meetups
    description: Meetups resource
    tags:
    # ..
    parameters:
    # ..
    get:
    # ...
    post:
    # ..
    61/98 — VarnaConf 2019 | @specter_bg

    View Slide

  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

    View Slide

  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

    View Slide

  64. Possible responses
    /meetups/{id}
    get:
    responses:
    '200':
    content:
    application/json:
    schema:
    # ...
    '404':
    content:
    application/problem+json:
    # ...
    64/98 — VarnaConf 2019 | @specter_bg

    View Slide

  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

    View Slide

  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

    View Slide

  67. nullable fields
    city:
    description: either a string or null
    type: string
    nullable: true
    67/98 — VarnaConf 2019 | @specter_bg

    View Slide

  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

    View Slide

  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

    View Slide

  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

    View Slide

  71. Components
    components:
    schemas:
    # ...
    responses:
    # ...
    parameters:
    # ...
    requestBodies:
    # ...
    headers:
    # ...
    examples:
    # ...
    71/98 — VarnaConf 2019 | @specter_bg

    View Slide

  72. Tools
    72/98 — VarnaConf 2019 | @specter_bg

    View Slide

  73. Editors
    73/98 — VarnaConf 2019 | @specter_bg

    View Slide

  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

    View Slide

  75. Swagger Editor
    75/98 — VarnaConf 2019 | @specter_bg

    View Slide

  76. Apicurio
    76/98 — VarnaConf 2019 | @specter_bg

    View Slide

  77. OpenAPI GUI
    77/98 — VarnaConf 2019 | @specter_bg

    View Slide

  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

    View Slide

  79. Linters
    79/98 — VarnaConf 2019 | @specter_bg

    View Slide

  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

    View Slide

  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

    View Slide

  82. Documentation
    82/98 — VarnaConf 2019 | @specter_bg

    View Slide

  83. Swagger UI - least favorite
    83/98 — VarnaConf 2019 | @specter_bg

    View Slide

  84. Widdershins + Slate / Shins.js
    84/98 — VarnaConf 2019 | @specter_bg

    View Slide

  85. ReDoc
    85/98 — VarnaConf 2019 | @specter_bg

    View Slide

  86. Mock Servers
    86/98 — VarnaConf 2019 | @specter_bg

    View Slide

  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

    View Slide

  88. Testing
    88/98 — VarnaConf 2019 | @specter_bg

    View Slide

  89. Postman
    → import trough the app
    → import using the API
    89/98 — VarnaConf 2019 | @specter_bg

    View Slide

  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

    View Slide

  91. Why convert?
    best of both worlds
    (sort of)
    91/98 — VarnaConf 2019 | @specter_bg

    View Slide

  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

    View Slide

  93. Code Generation
    93/98 — VarnaConf 2019 | @specter_bg

    View Slide

  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

    View Slide

  95. openapi.tools
    thanks to Phil Sturgeon and Matthew Trask
    95/98 — VarnaConf 2019 | @specter_bg

    View Slide

  96. Thank you!
    96/98 — VarnaConf 2019 | @specter_bg

    View Slide

  97. Questions?
    97/98 — VarnaConf 2019 | @specter_bg

    View Slide

  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

    View Slide