Presentation

# Contract-first API development
## using the OpenAPI Specification<br/>(fka Swagger)

???
- Hi and welcome to: 
- Contract-first API development using the OpenAPI Specification formerly known as Swagger

---

???
- I'm Dave Forgac and this is Ian Zelikman.
- We used to work together on the API team at American Greetings, but he's since moved on to a different job at IBM Watson Health.
- You can read our bios on the conference site if you want to know more.
- One thing I would like to point out is that we are not affiliated with the OpenAPI Initiative.
- We are simply users of and fans of the technology.

---

# Questions

---

# BetterAPIs.com
## `https://github.com/tylerdave/OpenAPI-Tutorial/`

???
- We put together a simple website for this tutorial.
- It is available at BetterAPIs.com
- If you haven't done so already, this is where you can find instructions for installing the tutorial prerequisites
- In case you're having trouble downloading the installers we have a few USB flash drives we can pass around
- We'll also have a link to a survey for you to provide feedback at the end.
- We'd really appereciate you taking the time to compmlete that so we can improve our tutorial for next time

---

# Updates

### Get repo updates

```
git pull
```

### Reprovision VM

```
vagrant suspend  
vagrant reload --provision
```

### Log in

```
vagrant ssh
```

???
- If you don't have the prerequisites installed yet, you should be following the directions to do so now.
- Once do, we'd like you to verify that they're working.

---

# Backup Plan

## `http://editor.swagger.io/`

???
- Before we start the tutorial lessons I'm going to run through some background information.
- During this time Ian will be walking around helping people get things installed.
- If you need help, raise your hand and he'll try to get to you.
- If you're not able to get the prerequisites installed by the time we're ready to start the lessons:
- You can use the online editor to follow-along for the first half and then we can try to get things working during the break

---

# Background

???
- Before we really get started I want to go over some terminology and concepts
to make sure we're all on the same page.

---
class: center, padded-top

# REST

???
- REST is a *HUGE* topic
- For our purposes you just need to know a few things

## ~~Standard~~

???
- It's not a standard

## Architectural Style

???
- It's an architctural-style

## HTTP w/ Constraints

???
- For an API to be truly RESTful it needs to adhere to specific constraints:
  - Client-Server, Stateless, Cache, Interface / Uniform Contract, Layered System, Code-On-Demand

## REST-inspired HTTP APIs

???
- Most APIs don't fully adhere to these constraints
- But they do follow some of the patterns, most commonly
  - mapping HTTP methods to actions
  - mapping URL paths to resources or objects
- So we're really talking about REST-like or REST-inspired HTTP APIs

---
class: center, padded-top

# API Contract

???
Next is the idea of an API contract

## Client ↔ Provider

???
- Like a legal contract: 
  - It's an agreement between client and API provider
  - It should be negotiated
--

## Interface Specification

???
- The contract includes technical specification of how requests & responses should work

## SLA, ToS, Limits, Pricing, etc.

???
- It also includes other parts of agreement like SLA, rate limits, pricing tiers, etc

---
class: center, padded-top

# JSON
--

## JavaScript Object Notation
--

```
{
    "things": [
        "foo", 
        "bar"
    ], 
    "message": "Hello, World!"
}
```

???
- Just in case anyone isn't familiar...
- ~ Stands for JavaScript object notation
- It's a way to serialize object data
- ~ Will look pretty familiar if you've done much with javascript in recent years

---

# JSON Schema
--

```
{
    "title": "Example Schema",
    "type": "object",
    "properties": {
        "displayName": {
            "type": "string"
        },
        "age": {
            "description": "Age in years",
            "type": "integer",
            "minimum": 0
        }
    },
    "required": ["firstName", "lastName"]
}
```

???
- JSON schema is a standard specification for describing your data format
- It is written in JSON itself
- Used in data validation and automated testing

---

# YAML
--

## Serialization format
--

## (More) human-readable
--

## Superset of JSON
--

## Language Support

???
- YAML stands for YAML aint markup language
- ~ It's a serializatin format
- ~ meant to be more readable than JSON
- ~ It's actually a superset of JSON and can be converted to JSON
- ~ It has broad language support so it's starting to be used in a lot of places

---

## YAML Basics - Lists

```
---
colors:
  - red
  - green
  - blue
...
```

---

## YAML Basics - Dictionaries

```
---
session:
  title: Contract-First API Development
  type: tutorial
...
```

---

## YAML Basics - Spanning

```
---
description: |
  This is a long description
  using a pipe
  which will preserve newlines.
description2: >
  This is a long desciption using > which
  will ignore
  new
  lines.
...
```

---

## YAML Basics - Nesting

```
---
session:
  name: Contract-First API Development
  type: tutorial
  topics:
    - apis
    - openapi specification
    - swagger
  languages: ['java', 'nodejs', 'python']
  description: >
    A really useful tutorial during which you'll
    learn about API specifications and stuff.
...
```

---

# Compare

```
"Talk": {
  "type": "object", 
  "properties": {
    "id": {
      "type": "integer"
    }, 
    "title": {
      "minLength": 1, 
      "type": "string", 
      "maxLength": 144
    }
  }
}
```
]
]

```
Talk:
  type: object
  properties:
    id:
      type: integer
    title:
      type: string
      minLength: 1
      maxLength: 144
```

]
]

---

# API Definitions
--

## WSDL / WADL
--

## Swagger -> OpenAPI Spec
--

## API Blueprint
--

## RAML

---

# OpenAPI Spec
--

## Structure
--

## History
--

## Future

---

# OpenAPI 3.0
--

## Coming Soon
--

## Tooling to Follow

???
Note that a new version is being released soon
Tooling will take some time to catch up

---

# This Tutorial

---

# Goals
--

## OpenAPI Spec
--

## Testing
--

## Mock
--

## Basic Implementation
--

## Documentation

---

## Repo Layout

```
├── implementation
│   └── ...
├── lessons
│   ├── lesson-1.01
│   │   ├── default_broken.yaml
│   │   └── solution.yaml
│   ├── lesson-1.02
│   │   ├── example.json
│  ... ...
│   ├── lesson-2.01
│   │   └── README.md
│   └── ...
├── presentation
│   └── ...
└── work
```

---

# Synced Folder

### Repo dir on host

### mapped to

### `/home/ubuntu/tutorial-repo/` on VM

---

# Lessons

## Instructions

- Work in `work` directory
  - Via editor on host machine
  - Or via editor in VM terminal
- Save `betterapis.yml`
- Run validator within VM:
  - `swagger validate tutorial-repo/work/betterapis.yml`

---

# Lesson Solutions

## Done?

- Compare with contents of `lessons/lesson-x.xx/solution.xxx`

## Stuck?

- Copy `lessons/lesson-x.xx/solution.xxx` to `work`

---

# Tutorial

---

# Lesson 1.01: Setup

## Goals

- Explore the environment.
- Look at some Open API example specs and exercise the tools we will use.

???
- We will start every lesson with **goals**. Then some **theory** or **demo** and then and *excercise*.
  In the end we will review some **notes** about the **solution**.
- This is an introductory lesson that will help you familiarize with the **structure of the lessons**.
- We will also look at the tools we will use, and initial **taste** of the **Open API specification.**
---

# Lesson 1.01: Setup

## Tooling

- Swagger editor:

`http://localhost:8000/`

- Validator:

```
swagger validate tutorial-repo/lessons/lesson-1.02/solution.yaml
```

???
- In the environment you downloaded you will be able to run the **swagger editor** that I will now show.
- There are several examples that come with the editor. We will look at **default.yaml**.
- This is a good basic example of how a spec file will look.
- The spec is very readable and not just easily parsed by automatic tools. But we will look at every
  element in detail in later lessons.
- As you start working with the editor. You can see it does very good **validation**.
- The editor gives you good validation but if you also want to combine working in command line
  or want to know how to automate this process you can use the cli.

---
class: lesson

# Lesson 1.01: Setup

## Exercise Instructions

- Load several examples from the swagger editor, review them.

- Import the broken examples from lesson-1.01 directory.
  Try fixing the errors.

???

- Make sure to familiarize yourself with the swagger examples before trying to fix errors.

- Each file will have one error, if you are having problem fixing it you can look at the example
  with similar name.
---

# Solution 1.01

## Notes

- Got familiar with basic OpenAPI Spec structure

???
- In the exercise you had the opportunity to better familiarize yourself with Open API spec structure.
- **echo_broken** had a missing colon
  **minimal_broken** has bad indentation
  **default_broken** had no space after colon

---

# Lesson 1.02: Hello, World!

## Goals

- Building a first (basic) spec.

???
- The goal now is to take **in depth look** at Open API spec.
- We start with a very basic (and valid) spec in this lesson and each lesson we will add functionality.
- In the end you will have an example showing how to document all the main features of your API using
  OpenAPI spec.

---

# YAML Example

???
- Let's open the **example.yaml** file.
- This was build from examples you can find on the **Open API github** documentation.
- Swagger is build out of objects and here you can see the root object with several fields.
- The required fields are: **swagger** (must be 2.0 now), **info** (object), **paths**.
- We want to start from **more complete example**, that has more complete meta-data and hence added
  more fields than mandatory to the info, **host basepath**, **consumes**, **produces** etc.
  The fields are very self descriptive.
- consumes/produces are the mime types that are supported and they are lists.
---

# JSON Example

???
- When opening a json representation. The editor renders as YAML.
- You are **free** to write it using **Json or YAML**.
  The specification have example for both.

---
class: lesson

# Lesson 1.02: Hello, World!

## Exercise Instructions

- Build an API for a conference called `betterapis`
- Include metadata as shown in the example
- Paths are empty for now

???
- We will now start to build our API. It is for  conference called betterapis.
  This is just a first step and we will build it **incrementally**.
- You are free to come up with meta data as you like, only requirement that it will be valid.
- If get stuck, remember to **consult the example** in lesson directory or the Open API spec.

---

# Solution 1.02

## Notes

- This solution might be a bit different than yours in regards to the metadata.
- Valid Spec!

???
- You can see some **metadata** that is different.
- This is **valid spec** even though we do not support any functionality.
  It promotes building the spec in an incremental way.

---
class: lesson

# Lesson 1.03: Pets

## Goals

- Get familiar with defining paths.

???
- This lesson is intended to just show the **path object**.
- It is another (small)step in adding functionality to the API.

---

# Lesson 1.03: Pets

## Basic Path

```
    /pets:
      get:
        summary: Get a list of pets
        description: Retrieve a list of pets
        responses:
          201:
            description: OK
```

???
- An example of the paths object that contains a list of **path Item object**
- Path item object is **relative to the base path** and contains a list of valid http operations
- **operation object** Is where the interesting logic happens and it holds some metadata about the
  operation (summary, description) and as we will see later a bit more.
- **response object** is how we can define the entire response body/headers etc. For now we just see
  one response code supported and description.
  Later we will expand to describe all the data returned in this response.

---
class: lesson

# Lesson 1.03: Pets

## Exercise Instructions

- Add two paths to the API: `/talks` `/speakers`.
- Both paths only support GET and only return status code 200.

???
- These are the two main paths we will work with. We want to start with a small step to define them
  as you might sometime do with not having the documentation complete and then iterate on that.

---

# Solution 1.03

## Notes

- We defined the very basic fields and objects needed for a valid path.

???
- You saw how you can define a **path** and an **action** on it.
  Those are the main building blocks for the HTTP protocol and REST APIs.
  You can see how you can define other paths, actions and response codes.
- Now that we defined the path in the most basic way we can move forward to a more challenging
  definition of the paths.

---

# Lesson 1.04: Registration

## Goals

- Learn to define complex operations on the API.

---

# Lesson 1.04: Registration

## Paths, Actions

```
paths:
    /pets:
      post:
        summary: Add pet to DB
        description: Results in new pet information added to the DB
        parameters:
          - name: pet
            in: body
            description: Pet details
            schema:
              required: [name, status]
              properties:
                name:
                  type: string
                  description: The pet name
                  ...
```

???
- We have seen the path and operations objects in the last lesson. Now we see how to define the **request**.
- **parameters** is what is driving the operation as it is the data passed and it is an **array**
  of this object.
- The parameter has a **name** to identify it. the **in** keyword is very important as it describes where
  in the request the parameter is passed. In this case it is in the **body**. It can also be:
  **path, header, query, body, form**
- The data types that are supported are derived from json schema draft 4: integer, long, float, double, string,
  byte, binary, boolean, data, dateTime, password.
  One type that is not in the json schema is **file** and is supported as well.
- **required** field specifies for us which fields would be required to pass which are optional.
- **schema object** is based on json schema specification draft 4. Each property has a set of
  attributes such as we see here **type**, and **description** but can also but other like
  **title, pattern, minLength, maxLength** etc.

---

# Lesson 1.04: Registration

## Paths, Actions (contd.)

```
        responses:
          201:
            description: Created new pet in the database
            schema:
              required: [pet-id]
              properties:
                pet-id:
                  type: number
                  description: Unique Id for the pet in the system

```

???
- This continues the action we saw in the previous slide.
- Responses is a container with the **status codes** acting as the **field pattern** and inside we have
  as you see the **response object**
- Response object will have a **description**. Optional: **schema, headers and
  examples array**
---

# Lesson 1.04: Registration

## Exercise Instructions

- Add actions to support speaker registration and talk submission
- You are free to define the speaker and talk objects as you like as long as you define a unique id
  in both and exercise defining more than one basic type for the object properties.

???
- You will add the POST actions in order to register the speaker and submit talk.

- Free to be creative as would like in order to define the objects.

---

# Solution 1.04

## Notes

- Additional properties: `readOnly`, `format`, `pattern`

???
- The main difference you might have seen in the solution is we are using additional properties in
  the json schema. There are more in the specification and this gives you ability for more fine
  grained documentation.

- **readOnly** specifies that it is only passed in response but won't be passed on the request.

- **format** gives you more fine tuning of the type passed. int32(format) vs. integer(type).

---

# Lesson 1.05: The Minimalist API

## Goals

- Reusing definitions.
- Learn more in depth about action objects and request parameters.

???
- This is in my opinion where things get **interesting**.
- You will see how we can **reuse** elements of the API and not repeat.

---

# Lesson 1.05: The Minimalist API

## Path Parameter

```
  /pets/{pet-id}:
    parameters:
      pet-id:
        name: pet-id
        in: path
        description: Pet identifier
        type: number
        required: true
```

???
- Sometimes you want to have a parameter in the **path**.
  For example when you define the pet resource here.
- Notice how the **keyword** indicates the parameter is in the path and hence the name must match.
- Other than the name matching this is similar to parameter definition we saw earlier.

---
class: lesson

# Lesson 1.05: The Minimalist API

## Parameter Reuse

```
  /pets/{pet-id}:
    parameters:
      - $ref: '#/parameters/pet-id'

...

parameters:
    pet-id:
      name: pet-id
      in: path
      description: Pet identifier
      type: number
      required: true
```

???
- This parameter might be **reused** in other parts of your API.
- Open API spec supports defining parameters in a global spec (the **root** of your document).
  This way you can reuse them in different paths.
- As you can see once we have this definition we can just reuse the parameter using json schema
  keyword **$ref** In order to define in other places.

---

# Lesson 1.05: The Minimalist API

## Definitions Reuse

```
  ...
      schema:
        $ref: '#/definitions/Pet'
  ...
  definitions:
    Pet:
      type: object
      required: [name, status]
      properties:
    ...
    Pets:
      type: array
      items:
        $ref: "#/definitions/Pet"
```

???

- In a similar way to what we saw where we can define and reuse parameters we can do with any
  **general object** as we see here the object reused in an **array** definition.
- This really opens new options as we can reuse it not only in action object or responses but in other
  definitions as well.
- The **schema element is indented** in order to highlight that the
  **definitions container** is in the root of the document.
- We will later (perhaps) see that definitions can be even in **separate files**.

---

# Lesson 1.05: The Minimalist API

## Exercise Instructions

1. Refactor your API to use `Talk` and `Speaker` objects.
   Define `Talks` and `Speakers` objects based on the previous and update the responses from
   `/speakers` and `/talks` paths.
2. Add a two new paths `/speakers/{speaker-id}` and `/talks/{talk-id}`.
   Define all the CRUD operations for them and use parameter definition outside of the action for
   path parameter.

???
- This exercise is split into two distinct sections in order to more easily implement the definitions.
  You should first implement part 1 make sure it is valid and then continue to 1.
- **Talks** and **speakers** objects should be arrays.
- If encounter issues implementing part 1 you can consult solution specifically for this part.
- In part 2 only define 2xx responses. We will cover other responses later.

---
class: solution

# Solution 1.05

## Notes

- Time saving with definition. More readable.
- Example response in the solution

???
- We can right away see this would have been much more time consuming and less readable without the
  reusable definitions.
- In the **solution** you can also see an example in one of the **responses**.
  This will be helpful later.

---

# Lesson 1.06: Responses

## Goals

- Learn more about parameter definition via pagination
- Learn How to define reusable responses
- Default responses

???
- Even though we are calling this lesson and it will focus on responses we will start with a pagination
  example.
---

# Lesson 1.06: Responses

## Pagination

```
   parameters:
    - $ref: '#/parameters/page-size'
    - $ref: '#/parameters/page-number'
   ...
parameters:
  page-size:
    name: page-size
    in: query
    description: Number of items
    type: integer
    format: int32
    minimum: 1
    maximum: 100
    multipleOf: 10
    default: 10
```

???
- A very **common task** is to add pagination to actions. Almost every time we return an array.
- This illustrates a very easy addition of pagination.
- In addition to seeing some more detailed **parameter definition** (format, minimum, maximum etc..),
  What we see here is also that since **pagination** is very **common** you can just define it once
  and then **reuse** it in other endpoints.
- This way you not only save time on redefinition but **avoid mistakes** by changing your pagination
  only in one place.

---

# Lesson 1.06: Responses

## Response Definition

```
responses:
  ServerErrorResponse:
    description: Server error during request.
    schema:
      $ref: "#/definitions/Error"

definitions:
  Error:
    properties:
      code:
        type: integer
      message:
        type: string

```
???
- **responses** is another container at the root level where we can define for later use.
  The interesting thing here is that we can **define** the whole **response object** as we have seen before.
- Also note how we reuse the `Error` object.

---

# Lesson 1.06: Responses

## Default Response

```

/pets/{pet-id}/
  delete:
    responses:
      ...
      default:
        $ref: '#/responses/UnknownResponse'

responses:
  UnknownResponse:
    description: This response is not yet documented by this API.
```

???
- The **responses** object on action **MUST** have at least one **successful** response and all known errors.
  This requirement by the spec actually.

- The spec is flexible though to recognize that there might be responses that are not documented and
  allows us to define a **default** response.
  Note that this is not using an http code as a field name but uses the keyword **default**

---

# Lesson 1.06: Responses

## Exercise Instructions

- Add pagination to the `/talks` and `/speakers` paths. Pagination should be included by at least
  two parameters: `page-size`, `page-number`.
- Add the following responses to all paths: 400, 500, default.

---

# Solution 1.06

## Notes

- Functionality complete API

???
- I wanted you to look for a minute now at your API. Functionality wise this is very much complete.
  If you have written documentation for Rest API before without a spec you must know how complicated
  and sometime not very readable they become.
  This on the other hand is both **readable** and **parsable**.
  If you look at the right hand in your swagger
  editor you can see very readable and easy to understand HTML as well.
---