Bringing OpenAPI to DevOps

Transcript

1. Bringing OpenAPI to DevOps Vincenzo Chianese — @d3dvincent
2. Stoplight Monday, December 17, 2018 @d3dvincent 2 Agenda • Where are we at with OpenAPI • Current usages and tools • What’s up with OpenAPI at runtime • Use cases • API Gateway support • What can we do better • Live demo • Takeaways and questions
3. Stoplight Monday, December 17, 2018 @d3dvincent 3 Vincenzo Chianese • vincenzo@express-gateway.io • vincenzo@stoplight.io • https://vncz.js.org/ • https://twitter.com/D3DVincent • https://github.com/XVincentX Software Developer @ Stoplight Maintainer @ Express Gateway Auth0 Ambassador Google Developer Expert
4. Stoplight Monday, December 17, 2018 @d3dvincent OpenAPI 4 The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for REST APIs, which allows both humans and computers to discover and understand the capabilities of a service Use cases for machine-readable API definition documents include, but are not limited to: interactive documentation; code generation for documentation, clients, and servers; and automation of test cases. — OpenAPI Official Repository
5. Stoplight Monday, December 17, 2018 @d3dvincent { "swagger": "2.0", "info": { "description": "This is a sample server Petstore server.", "version": "1.0.0", "title": "Swagger Petstore", "termsOfService": "http://swagger.io/terms/", "contact": { "email": "apiteam@swagger.io" }, "license": { "name": "Apache 2.0", "url": "http://www.apache.org/licenses/LICENSE-2.0.html" } }, 5 Interactive documentation ToC Request/ Response description Online client Linting Search Features Client generation Content/ Type
6. Stoplight Monday, December 17, 2018 @d3dvincent 6 Code generation { "swagger": "2.0", "info": { "description": "This is a sample server Petstore server.", "version": "1.0.0", "title": "Swagger Petstore", "termsOfService": "http://swagger.io/terms/", "contact": { "email": "apiteam@swagger.io" }, "license": { "name": "Apache 2.0", "url": "http://www.apache.org/licenses/LICENSE-2.0.html" } }, const client = require(‘petstore-client') (process.env.PETSTORE_API_KEY); client.pets.create({ name: 'Doogy', age: 2 }).then(() => { console.log("Pet created correctly!"); }).catch(() => { console.error("Something went wrong") }); Base URL and authentication URL mapping Parameters mapping Success and error handlers
7. Stoplight Monday, December 17, 2018 @d3dvincent 7 Automation of test cases Schema validation File coverage
8. Stoplight Monday, December 17, 2018 @d3dvincent 8 Linting Best Practices Business rules • Spectral • Open Source Linting Engine • Based on https://speccy.io • https://github.com/stoplightio/spectral
9. Stoplight Monday, December 17, 2018 @d3dvincent 9 What about the runtime?
10. Stoplight Monday, December 17, 2018 @d3dvincent 10 OpenAPI in your runtime: today • API Monitoring • API Usage Statistics • API Analysis and feedback collection
11. Stoplight Monday, December 17, 2018 @d3dvincent 11 OpenAPI as a source for verification client.pets.list() GET /api/pets
 HOST: petstore.com Accept: application/json • Most used endpoints • Most failing endpoints • Most common scenarios
12. Stoplight Monday, December 17, 2018 @d3dvincent 12 …what about ops? • Safely rollout a new API Section • Set an API Section as deprecated • Changes in security requirements • Changes in validation rules • Redirects
13. Stoplight Monday, December 17, 2018 @d3dvincent 13 API Gateway • Limited configuration surface • Almost 1:1 match with OpenAPI description file • (some) solutions can be declaratively configured
14. Stoplight Monday, December 17, 2018 @d3dvincent 14 AWS API Gateway • OpenAPI 2 support • OpenAPI 3 support (September 2018) • Proprietary extensions • Lack of an Document Upload API
15. Stoplight Monday, December 17, 2018 @d3dvincent 15 Axway API Gateway • OpenAPI 2 support • No custom extensions • Public API for configuration • Missing OpenAPI upload
16. Stoplight Monday, December 17, 2018 @d3dvincent 16 Apigee Edge • Unclear OpenAPI supported version • No documented extensions • Project Upload API
17. Stoplight Monday, December 17, 2018 @d3dvincent 17 On premise/hybrid solutions The situation does not seem to be that better Express Gateway
18. Stoplight Monday, December 17, 2018 @d3dvincent 18 Talk is cheap; show me the code
19. Stoplight Monday, December 17, 2018 @d3dvincent 19 Takeaways and open questions • Tooling hasn’t caught up yet with OpenAPI 3.0 • Implementations difficulties • OAS3 is not yet spread • OAS2 is good enough • OpenAPI aren’t a first class citizens for API Gateways • They just do not care of its support • Not the right tool for the job • OpenAPI documents alone aren’t enough to describe all the aspects of an API • OpenAPI specifications need to be expanded
20. Thank you! Questions? • vincenzo@express-gateway.io • vincenzo@stoplight.io • https://vncz.js.org/ • https://twitter.com/D3DVincent • https://github.com/XVincentX