Interoperable REST APIs with OpenAPI 3 and Connexion

Welcome to the API-First training!

Intro slides

Agenda

• Course environment
• Interoperability: Goals, REST, RPC, Contract First.
• API modeling with OpenAPI 3
• The connexion framework, mocking our API model, returning Problem objects
• Implementing the endpoints without request parameters and with request parameters
• Using YAML features and $ref to enforce API behavior
• Authorization: basic auth
• Service management with interoperabile throttling headers
• [Pagination]s(/notebooks/notebooks/08-pagination.ipynb)
• Validation intro

Bonus tracks:

• Authorization with JWT

Strategy

We will adopt an iterative strategy, progressively:

1. introduce more OAS3 features
2. write OAS3 specifications
3. implement the associated code
4. repeat

Jupyter

is the course environment in your browser.

It's not a way for not doing your homework ;)

You can:

• open a terminal on the local machine
• edit an existing file
• add more cells with ALT+ENTER

FIXME: Go to the basic python course

Course services and directories

• IP:8888/notebooks this Jupyter notebook
• IP:8080 the API Documentation Web UI (Swagger UI)
• IP:5000 the flask application we will execute during the course

Once you open the terminal you will find all the course under /code.

/code/
│  
└── notebooks    # All notebooks!
    ├── oas3     # OpenAPI specifications, files and exercises
    │  
    └── startup  # startup files for jupyter, don't touch ;)

Customizing the app

To simplify things, during the training we'll run the connexion-flask app with the connexion run command. You can always provide a custom __main__.py like you normally do with your flask app (eg: enable TLS, ...).

Whenever you complete an exercise, you should run

connexion run /code/notebooks/oas3/openapi.yaml

If you can't do an exercise

During the course we'll write two files:

• openapi.yaml with the API specifications;
• api.py with the API implementation

You can find solutions in the training directory, so if you can't complete your openapi.yaml you can run the solution (which ends with -ok.yaml instead, with

connexion run /code/notebooks/oas3/ex-03-02-path-ok.yaml

# An API Editor is available at the following address
print(oas_editor_url(''))

# You can evaluate maths and strings
s = 1
print("a string and the number " + str(s))

s = s + 1
print("now s is increased " + str(s))

# Note: all notebooks preload the definitions in
!ls -l /root/.ipython/profile_default/startup

Exercises

Exercise solutions are folded. You can show them clicking on the + sign.

Don't do that :D just try and

Setup with digitalocean (if you don't have your server)

Create a docker-18-04 droplet and ssh into it.

Setup example

Docker must listen on 172.17.0.1:2735

# vim /etc/systemd/system/multi-user.target.wants/docker.service
[Service]
...
ExecStart=/usr/bin/dockerd -H fd:// -H tcp://172.17.0.1:2375
...
#wq!

systemctl daemon-reload
systemctl restart docker

Clone and start

git clone https://github.com/ioggstream/python-course.git
cd python-course/ansible-101
make course

Connect to jupyter

firefox http://43.32.54.212:8888/tree/notebooks/?token=....