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.

Transcript

1. DESIGN FIRST APIS
   WITH OPENAPI AND FRIENDS
   1/92 — BulgariaPHP 2019 | @specter_bg
   

   View Slide

2. SO YOU NEED TO BUILD
   AN API
   2/92 — BulgariaPHP 2019 | @specter_bg
   

   View Slide

3. WHERE DO YOU
   START?
   3/92 — BulgariaPHP 2019 | @specter_bg
   

   View Slide

4. THE DATABASE?
   4/92 — BulgariaPHP 2019 | @specter_bg
   

   View Slide

5. THE CLIENTS?
   5/92 — BulgariaPHP 2019 | @specter_bg
   

   View Slide

6. THE CODE?
   6/92 — BulgariaPHP 2019 | @specter_bg
   

   View Slide

7. WHAT ABOUT DOCS?
   7/92 — BulgariaPHP 2019 | @specter_bg
   

   View Slide

8. WHAT ABOUT TESTS?
   8/92 — BulgariaPHP 2019 | @specter_bg
   

   View Slide

9. WHAT ABOUT VALIDATION?
   9/92 — BulgariaPHP 2019 | @specter_bg
   

   View Slide

10. YOU SOMEHOW MANAGE TO GET
    GOING AND PRODUCE SOMETHING
    WORKING
    10/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

11. BUT NOW YOU NEED TO
    CHANGE SOMETHING
    11/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

12. SOUNDS FAMILIAR?
    12/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

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
    

    View Slide

14. The backend developers said they
    can only return data from one
    table.
    — Mobile Developer
    14/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

15. The frontend devs want unrelated data.
    We'll just return everything.
    -- Backend Developers
    15/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

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
    

    View Slide

17. 17/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

18. COMMON PROBLEMS
    18/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

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
    

    View Slide

20. OUR PROCESS
    HAS FAILED US
    20/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

21. 1. LITTLE UPFRONT DESIGN
    WORK
    21/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

22. 2. UNANNOUNCED OR
    MISCOMMUNICATED
    CHANGES
    22/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

23. WASTE
    23/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

24. FRUSTRATION
    24/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

25. MORE MEETINGS
    25/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

26. WHAT CAN WE
    DO?
    26/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

27. Weeks of coding can save you
    hours of planning!
    — unknown
    27/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

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
    

    View Slide

29. ITERATE
    29/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

30. DESIGN IS NOT A ONE TIME EVENT.
    30/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

31. REPEAT THE PROCESS FOR EVERY CHANGE.
    31/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

32. PLANNING / DESIGN
    32/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

33. 33/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

34. API SPECIFICATIONS
    34/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

35. A CONTRACT
    BETWEEN THE API AND ITS USERS
    35/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

36. CHOOSE THE RIGHT ONE FOR YOU
    > OpenAPI
    > RAML
    > API Blueprint
    36/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

37. 37/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

38. FORMERLY KNOWN AS
    SWAGGER
    38/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

39. FORMERLY KNOWN AS
    SWAGGER
    39/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

40. OpenAPI
    40/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

41. ABOUT THE SPEC
    > has lots of tools
    > yaml or json based
    > very active community
    > widely adopted
    41/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

42. WRITE BY HAND OR USE A GUI?
    42/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

43. OPENAPI
    CRASH COURSE
    43/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

44. READ THE SPEC
    AT HTTPS://SPEC.OPENAPIS.ORG/OAS/V3.0.2
    44/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

45. BASIC STRUCTURE
    openapi: “3.0.0”
    info:
    # ...
    servers:
    # ...
    paths:
    # ...
    tags:
    # ...
    components:
    # ...
    45/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

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
    

    View Slide

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
    

    View Slide

48. WHAT CAN THE API DO
    paths:
    /meetups
    # ...
    /meetups/{id}
    # ...
    /meetups/{id}/events
    # ...
    48/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

49. A path description
    /meetups:
    parameters:
    # ..
    get:
    # ...
    post:
    # ..
    delete:
    # ..
    49/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

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
    

    View Slide

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
    

    View Slide

52. OPERATIONS
    get:
    operationId: findMeetups
    summary: Find Meetups
    description: Find and search for meetups
    tags:
    - meetups
    parameters:
    # ,..
    responses:
    # ...
    52/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

53. POSSIBLE RESPONSES
    /meetups/{id}
    get:
    responses:
    '200':
    content:
    application/json:
    schema:
    # ...
    '404':
    content:
    application/problem+json:
    # ...
    53/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

54. HEADERS
    headers:
    RateLimit-Limit:
    description: The number of allowed requests in the current period
    schema:
    type: integer
    54/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

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
    

    View Slide

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
    

    View Slide

57. NULLABLE FIELDS
    city:
    description: either a string or null
    type: string
    nullable: true
    57/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

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
    

    View Slide

59. OPENAPI 3.1
    59/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

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
    

    View Slide

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
    

    View Slide

62. GUI EDITORS
    62/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

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
    

    View Slide

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
    

    View Slide

65. 65/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

66. GATHER FEEDBACK
    66/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

67. DOCUMENTATION
    67/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

68. OPTIONS
    > ReDoc
    > Swagger UI (hosted option)
    > Stoplight Hosted
    68/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

69. 69/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

70. MOCK API
    GATHER FEEDBACK
    70/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

71. 71/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

72. OPTIONS
    > Prism
    > API Sprout
    > SwaggerHub
    > Roll your own
    72/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

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
    

    View Slide

74. IMPROVE THE
    DESIGN
    74/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

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
    

    View Slide

76. IMPLEMENTATION
    76/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

77. CODE GENERATION
    77/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

78. OPENAPI-GENERATOR
    > generate server stubs
    > generate clients
    > custom generators
    > some generators might be out of date
    78/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

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
    

    View Slide

80. VALIDATION
    80/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

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
    

    View Slide

82. TESTING
    82/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

83. MANUAL TESTING
    83/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

84. POSTMAN
    > Direct OpenAPI import trough GUI
    > Import with Postman API
    84/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

85. AUTOMATED TESTS
    85/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

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
    

    View Slide

87. IF YOU NEED MORE TOOLS
    OPENAPI.TOOLS!
    SAY THANKS TO MATT TRASK AND PHIL STURGEON!
    87/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

88. REPEAT
    88/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

89. BUILD
    SOMETHING AWESOME
    89/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

90. THANK YOU!
    90/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

91. QUESTIONS?
    91/92 — BulgariaPHP 2019 | @specter_bg
    

    View Slide

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
    

    View Slide