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

Design APIs and deliver what you promised

Design APIs and deliver what you promised

Kyle Fuller

October 16, 2019
Tweet

More Decks by Kyle Fuller

Other Decks in Technology

Transcript

  1. Design APIs and
    deliver what you
    promised

    View full-size slide

  2. Life Saving API
    Design APIs and deliver what you promised -- @kylefuller

    View full-size slide

  3. CALL /112
    Design APIs and deliver what you promised -- @kylefuller

    View full-size slide

  4. 404
    Not Found
    Design APIs and deliver what you promised -- @kylefuller

    View full-size slide

  5. Bad Developer
    Experience
    Design APIs and deliver what you promised -- @kylefuller

    View full-size slide

  6. Bad Developer
    Experience
    Design APIs and deliver what you promised -- @kylefuller

    View full-size slide

  7. Bad User
    Experience
    Design APIs and deliver what you promised -- @kylefuller

    View full-size slide

  8. Design APIs and deliver what you promised -- @kylefuller

    View full-size slide

  9. Documentation is
    the UI for an API
    Design APIs and deliver what you promised -- @kylefuller

    View full-size slide

  10. How do you test
    API Documentation?
    Design APIs and deliver what you promised -- @kylefuller

    View full-size slide

  11. You Don’t.
    Design APIs and deliver what you promised -- @kylefuller

    View full-size slide

  12. Agenda
    Design APIs and deliver what you promised -- @kylefuller

    View full-size slide

  13. Why Design First?
    Design APIs and deliver what you promised -- @kylefuller

    View full-size slide

  14. Think Before You
    Code
    Design APIs and deliver what you promised -- @kylefuller

    View full-size slide

  15. Think Before You
    Code
    Design APIs and deliver what you promised -- @kylefuller

    View full-size slide

  16. Collaborate
    Design APIs and deliver what you promised -- @kylefuller

    View full-size slide

  17. Doing Design First
    Design APIs and deliver what you promised -- @kylefuller

    View full-size slide

  18. GET /hotels
    Design APIs and deliver what you promised -- @kylefuller

    View full-size slide

  19. 404
    API Not Found
    Design APIs and deliver what you promised -- @kylefuller

    View full-size slide

  20. GET /hotels/{id}/facilities
    Design APIs and deliver what you promised -- @kylefuller

    View full-size slide

  21. ## Hotel [/hotels/{slug}]
    + Attributes
    + name: Sheraton
    + location
    + city: Vancouver
    + longtitude
    + latitude
    + email: [email protected]
    + Response 200 (application/json)
    + Attributes (Hotel)
    Design APIs and deliver what you promised -- @kylefuller

    View full-size slide

  22. Prototype &
    Develop
    Design APIs and deliver what you promised -- @kylefuller

    View full-size slide

  23. 1 + 1 = -7
    Design APIs and deliver what you promised -- @kylefuller

    View full-size slide

  24. Find bad API DX
    and errors before
    anyone else does
    Design APIs and deliver what you promised -- @kylefuller

    View full-size slide

  25. GET / HTTP/1.1
    Host: api.github.com
    200 OKAY
    Content-Type: application/json
    {
    "current_user_url": "/user",
    "authorisations_url": "/authorisations",
    "issues_url": "/issues",
    ...
    }
    Design APIs and deliver what you promised -- @kylefuller

    View full-size slide

  26. # GET /
    + Response 200 (application/json)
    + Attributes
    + *user_url*: /user
    Design APIs and deliver what you promised -- @kylefuller

    View full-size slide

  27. openapi: 3.0.0
    paths:
    /:
    get:
    responses:
    '200':
    content:
    application/json:
    schema:
    type: object
    additionalProperties:
    type: string
    example: /user
    Design APIs and deliver what you promised -- @kylefuller

    View full-size slide

  28. Design APIs and deliver what you promised -- @kylefuller

    View full-size slide

  29. # POST /sessions
    You can create a session proposal by sending a POST request
    with the speaker and the title. The proposal will be in a
    draft state until approved by the conference.
    + Request (application/json)
    + Attributes
    + title: Design APIs and deliver what you promised (required)
    + One Of
    + speaker: Kyle (required)
    + speakers: Kyle, Doe (array, required)
    Design APIs and deliver what you promised -- @kylefuller

    View full-size slide

  30. $ dredd api_specifications_conference.apib http://localhost:8000
    pass: POST (201) /sessions duration: 12ms
    complete: 1 passing, 0 failing, 0 errors, 0 skipped, 1 total
    complete: Tests took 12ms
    Design APIs and deliver what you promised -- @kylefuller

    View full-size slide

  31. # POST /sessions
    + Request (application/json)
    + Headers
    ```
    Authorization: Bearer ?>
    ```
    + Attributes
    + title: Design APIs and deliver what you promised
    Design APIs and deliver what you promised -- @kylefuller

    View full-size slide

  32. from dredd_hooks import before_each
    @before_each
    def attach_authorization_header(transaction):
    transaction['request']['headers']['Authorization'] = \
    'Bearer ???'
    Design APIs and deliver what you promised -- @kylefuller

    View full-size slide

  33. from dredd_hooks import before_each
    from hotels.auth.models import User, Session
    @before_each
    def attach_authorization_header(transaction):
    user = User.get_or_create(username='kyle')
    session = Session.create(user=user)
    transaction['request']['headers']['Authorization'] = \
    'Bearer {}'.format(session.token)
    Design APIs and deliver what you promised -- @kylefuller

    View full-size slide

  34. Server:
    Implementation
    Testing
    Design APIs and deliver what you promised -- @kylefuller

    View full-size slide

  35. Client:
    Implementation
    Testing
    Design APIs and deliver what you promised -- @kylefuller

    View full-size slide

  36. API Description
    Coverage
    Design APIs and deliver what you promised -- @kylefuller

    View full-size slide

  37. Dredd
    GET dredd.org
    Design APIs and deliver what you promised -- @kylefuller

    View full-size slide

  38. EOF
    Design APIs and deliver what you promised -- @kylefuller

    View full-size slide