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. Documentation is the UI for an API Design APIs and

    deliver what you promised -- @kylefuller
  2. ## 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
  3. 1 + 1 = -7 Design APIs and deliver what

    you promised -- @kylefuller
  4. Find bad API DX and errors before anyone else does

    Design APIs and deliver what you promised -- @kylefuller
  5. 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
  6. # GET / + Response 200 (application/json) + Attributes +

    *user_url*: /user Design APIs and deliver what you promised -- @kylefuller
  7. 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
  8. # 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
  9. $ 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
  10. # 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
  11. 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