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 ratelimit headers
  • Pagination
  • 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:5000 the flask application we will execute during the course

Once you open the terminal you will find the course under:

  • notebooks if you run it locally;
  • /code/notebooks if you are on docker
/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 app with the connexion run command.

Whenever you complete an exercise, you should run the API with:

connexion run oas3/openapi.yaml

Not covered in this workshop: if you need to tweak your application, you can still create a connexion app and run it with an asgi container:

In [ ]:
from connexion import AsyncApp

def main():
    """
    Run me with
    $ uvicorn api:main --port ... 
    """
    app = AsyncApp(...)
    app.add_api( ...) 
    ...
    return app

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 oas3/ex-03-02-path-ok.yaml

Clone and start¶

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

Connect to jupyter¶

open http://localhost:8888/tree/notebooks/?token=....