The Open API Specification

aka documenting your work

Objectives

• Describe the importance of documenting an API
• Use a strategy to document your API
• Use a cool editor to document your API
• Write YAML
• Use a "specification" just like a real programmer

Documenting APIs - why?

Documenting APIs

Really think about your API before building

Documenting APIs

Really think about your API before building

Make an API someone else might like to use

Documenting APIs

Really think about your API before building

Make an API someone else might like to use

Easier to collaborate- defined inputs and outputs

Documenting APIs

Really think about your API before building

Make an API someone else might like to use

Easier to collaborate- defined inputs and outputs

Work with an API before it's finished

Document First

Document First

(It's harder to document after the fact)

Plan By Documenting

Kill two birds with one stone

Code festers without documentation

Code festers without documentation

It grows unpredictably and starts to smell

It's really easy to document an API

It's really easy to document an API

APIs are predictable

Swagger

Swagger

Swagger

The Open API Specification

Just look.

Documenting an API

1. List the endpoints
2. Define each method
3. Determine required parameters
4. Document successful responses
5. Document error responses

1. List the endpoints

/pet

/pet/findByStatus

/pet/findByTags

/pet/{id}

1. List the endpoints

/store

/store/inventory

/store/order

1. List the endpoints

/user

?

2. Define each method

GET /pet/{id}

PUT /pet/{id}

DELETE /pet/{id}

POST /pet

3. Determine required parameters

POST /pet

name - string, required

category - string, required

photoUrls - array, optional

PhotoURL

url - string, required

status - string, required

description - string, optional

4. Document Successful Responses

POST /pet - 201

{ 
    "id": 7431699383703929000, 
    "name" : "Scruffy",
    "photoUrls": [], 
    "tags": [] 
}

5. Document Error Responses

POST /pet - 406

{ 
    "err": "TypeError, 
    "description" : "Could not insert pet, missing field: name",
}

Using The Swagger Editor

http://editor.swagger.io/

YAML

Yet Another Markup Language

YAML

Yet Another Markup Language

it's really called that

An Example

swagger: "2.0"
info:
  title: Uber API
  description: Move your app forward with the Uber API
  version: "1.0.0"
# the domain of the service
host: api.uber.com

Swagger Doc Structure

• Meta - Info about the API
• Paths - listing of API paths
• Definitions - Models in your API

Swagger Doc Structure

Meta

# this is an example of the Uber API
# as a demonstration of an API spec in YAML
swagger: "2.0"
info:
  title: Uber API
  description: Move your app forward with the Uber API
  version: "1.0.0"
# the domain of the service
host: api.uber.com
# array of all schemes that your API supports
schemes:
  - https
# will be prefixed to all paths
basePath: /v1
securityDefinitions:
  apikey:
    type: apiKey
    name: server_token
    in: query
produces:
  - application/json

Swagger Doc Structure

Paths

paths:
  /products:
    get:
      summary: Product Types
      description: The Products endpoint returns information about the Uber products offered at a given location. The response includes the display name and other details about each product, and lists the products in the proper display order.
      parameters:
        - name: latitude
          in: query
          description: Latitude component of location.
          required: true
          type: number
          format: double
        - name: longitude
          in: query
          description: Longitude component of location.
          required: true
          type: number
          format: double
      security: 
        - apikey: []
      tags: 
        - Products
      responses:  
        200:
          description: An array of products
          schema:
            type: array
            items:
              $ref: '#/definitions/Product'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'

Swagger Doc Structure

Definitions

definitions:
  Product:
    properties:
      product_id:
        type: string
        description: Unique identifier representing a specific product for a given latitude & longitude. For example, uberX in San Francisco will have a different product_id than uberX in Los Angeles.
      description:
        type: string
        description: Description of product.
      display_name:
        type: string
        description: Display name of product.
      capacity:
        type: integer
        description: Capacity of product. For example, 4 people.
      image:
        type: string
        description: Image URL representing the product.