API First with Connexion - PyConWeb 2018
Connexion is an open source API first REST framework for Python, built on top of Flask and based on OpenAPI/Swagger, targeted for microservice development. Connexion automagically handles request routing, oauth2 security, request validation and response serialization based on an OpenAPI 2.0 Specification file in YAML, so you don’t have to care about boilerplate anymore. Because it is based on Flask it supports everything that Flask does, including deployment options and extensions. At Zalando we’ve adopted “API First” as one of our key engineering principles, to ensure our API are robust, consistent, general and abstracted from specific implementation and use cases. But when we tried to implement this principle for the first time we were faced with the lack of a python framework to achieve it in a easy fashion - there were several frameworks that produce a swagger definition from the implementation but none that do it the other way around - so we decided to fill that gap. Henning will show how to get started with OpenAPI+Connexion, present some real-world use cases and deployment options such as Kubernetes.
API First with Connexion - PyConWeb 2018
- 1. PyConWeb 2018 2018-07-01 HENNING JACOBS @try_except_ API First with Connexion
- 2. 2 ZALANDO AT A GLANCE ~ 4.5billion EUR revenue 2017 > 200 million visits per month > 15.000 employees in Europe > 70% of visits via mobile devices > 23 million active customers > 300.000 product choices ~ 2.000 brands 15 countries
- 3. 3 ZALANDO TECH ~ 2.000 Employees in Tech > 200 Delivery teams
- 4. 4 API FIRST
- 5. 5 API FIRST • Define REST API before implementation • API definition is contract between teams • Includes validation & documentation
- 14. 14 Python?
- 16. 16 info: {title: "Pet Shop Example API", version: "0.1"} paths: /pets: get: operationId: app.get_pets parameters: - name: animal_type in: query type: string responses: 200: schema: type: array items: $ref: '#/definitions/Pet' /pets/{pet_id}: get: operationId: app.get_pet parameters: - name: pet_id in: path type: string required: true
- 17. 17 info: {title: "Pet Shop Example API", version: "0.1"} paths: /pets: get: operationId: app.get_pets parameters: - name: animal_type in: query type: string responses: 200: schema: type: array items: $ref: '#/definitions/Pet' /pets/{pet_id}: get: operationId: app.get_pet parameters: - name: pet_id in: path type: string required: true
- 18. 18 CONNEXION: USAGE PETS = {} def get_pets(animal_type=None): return [pet for pet in PETS.values() if not animal_type or pet['animal_type'] == animal_type] def get_pet(pet_id): pet = PETS.get(pet_id) return pet or ('Not found', 404) # ... app = connexion.App(__name__) app.add_api('swagger.yaml') app.run(port=8080, server='gevent') https://github.com/zalando/connexion
- 19. 19 QUICKSTART WITH SWAGGER CODEGEN wget http://central.maven.org/maven2/io/swagger/swagger-codegen-cli/2.3.1/swagger -codegen-cli-2.3.1.jar -O swagger-codegen-cli.jar java -jar swagger-codegen-cli.jar generate -i swagger.yaml -l python-flask docker build -t myapp . docker run -it -p 8080:8080 myapp Swagger's "python-flask" is actually Connexion! https://github.com/swagger-api/swagger-codegen
- 20. 20 CONNEXION FEATURES • Path, query and body params mapped to Python args • Bundled Swagger UI (served on /ui/ path) • Automatic JSON serialization • Schema validation for HTTP request body and query params: • required object properties • primitive types (string, integers, etc) • date/time values • string lengths • min/max values • regular expressions https://github.com/zalando/connexion
- 22. 22 SWAGGER CODEGEN.. docker run -it -p 8080:8080 swagger-codegen-server ... OAuth2 token info URL missing. **IGNORING SECURITY REQUIREMENTS** * Serving Flask app "__main__" (lazy loading) * Environment: production WARNING: Do not use the development server in a production environment. Use a production WSGI server instead. * Debug mode: off * Running on http://0.0.0.0:8080/ (Press CTRL+C to quit)
- 23. 23 CONSIDERATIONS • WSGI server? • Runtime? • Target environment? • High availability? • Performance?
- 24. 24 CONSIDERATIONS • WSGI server? gevent • Runtime? Docker, image ~74MiB • Target environment? Kubernetes • High availability? multiple pods, readinessProbe • Performance? load test https://github.com/hjacobs/connexion-example-redis-kubernetes
- 26. 26 KILLING REDIS kubectl get pod NAME READY STATUS RESTARTS AGE connexion-example-67c64766f5-rgmmz 1/1 Running 0 55s connexion-example-67c64766f5-rwjt7 1/1 Running 1 1h connexion-example-redis-0 0/1 Terminating 1 1h https://github.com/hjacobs/connexion-example-redis-kubernetes
- 28. 28 EXAMPLE #2: ZALANDO AWS CREDENTIALS https://github.com/zalando-stups/aws-credentials-service
- 31. 31 OPEN SOURCE Zalando's RESTful API Guidelines https://github.com/zalando/restful-api-guidelines IntelliJ IDEA Swagger Editor Plugin https://github.com/zalando/intellij-swagger Zally API Linter https://github.com/zalando/zally Connexion https://github.com/zalando/connexion Connexion Examples https://github.com/hjacobs/connexion-example https://github.com/zalando-stups/aws-credentials-service
- 32. QUESTIONS? HENNING JACOBS HEAD OF DEVELOPER PRODUCTIVITY henning@zalando.de @try_except_ Illustrations by @01k