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
   

   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: boyan.yordanov.dev@gmail.com
    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