The fairytales about API deployments

Transcript

1. "The good must be put in the dish, the bad you may eat if you wish." - The fairytales about API deployments Daniel Kocot, Senior Solution Architect / Head of API Experience & Operations
2. Name: Daniel Kocot Role: Senior Solution Architect / Head of API Experience & Operations Email: Twitter: @dk_1977 LinkedIn: daniel.kocot@codecentric.de https://www.linkedin.com/in/danielkocot/
3. Once upon a time…​
4. there was the idea of API Management
5. and Gartner brought up another idea of "Full Lifecycle API Management".
6. So all vendors of API Management solutions claimed that their solution is "Full Lifecycle".
7. What does "Full Lifecycle" mean? Writing API definitions not from scratch Using an API Design Library Linting API definitions from the beginning of the writing process Using Contract, Content, Variation and Integration Tests Deploying API Definitions to specific targets Using pipelines to automate the things Observability
8. But there is no solution for the "Full Lifecycle" available in the market.
9. So stop and one step back…​
10. It’s about time for three fairytales around the deployment of APIs
11. #1 Write code first then generate the API description by the pipeline
12. What?
13. API first An API is the first (and often only) interface to users of an application An API comes first — before the implementation An API is described (documented) or self-descriptive
14. API as a (Digital) Product
15. OpenAPI / AsyncAPI
16. Use of references with $ref local '#/components/schemas/myElement' remote 'myElement.yaml' url 'http://path/to/your/myElement.yaml'
17. Goal: Establishing guidelines and a design library
18. Use of OpenAPI Extensions/X-Objects to handle own or vendor needs x-vendor-…​ x-…​ Supported by: root level info paths operation parameters responses tags security schemes
19. Configuration of cross-cutting concerns and org specific needs with OpenAPI Extensions
20. #2 Deploy the definition as an artifact near by the code
21. How?
22. Deployment Steps
23. Bundling the API Definition npx @redocly/openapi-cli bundle definitions/news.yaml --output output/news.yaml
24. Linting npx @redocly/openapi-cli stats definitions/news.yaml npx @redocly/openapi-cli lint output/news.yaml npx @stoplight/spectral-cli lint --fail-severity warn output/news.yaml
25. Linting - Spectral Ruleset extends: spectral:oas rules: contact-properties: info include-title: description: Info section has to include a title as identifying name of the API. given: $.info severity: error then: field: title function: truthy include-version: description: Info section has to include a version following semantic rules. given: $.info severity: error then: field: version function: truthy valid-semantic-version: description: Versions are restricted to the format <MAJOR>.<MINOR>.<PATCH>, e.g. 1.0.0. See http given: $.info severity: error then: field: version function: pattern
26. Tests docker run --init -v $(pwd)/output:/tmp --name prism-container --rm -d -p 4010:4010 stoplight/prism: npx @apideck/portman@latest -l output/news.yaml -o output/newsCollection.json -n true -c portman-con docker stop prism-container
27. Test Types Contract Content Variation
28. Test Configuration Creating YAML file(s) to configure the test types References are possible { "version": 1.0, "tests": { "contractTests": [], "contentTests": [], "variationTests": [], }, "globals": { "stripResponseExamples": true } }
29. Contract Testing Generating a Postman Collection after validating the contract
30. Content Testing Testing validation of response values
31. Variation Testing With contract testing we only tested the success known as the "happy path" With variation testing we have the happy path and the unhappy path With the unhappy path we want to verify that the API response is matching with the expected error response
32. Testing Artifacts After the tests we receive two artifacts bundled API definition Postman Collection in reference to the definition Both are now linted and tested
33. Deploy Depending on the deployment target Push of the OpenAPI Definition Converting the API definition to some Configuration as Code
34. #3 Every service has its own SwaggerUI representation of the corresponding API
35. Where?
36. Deployable Infrastructure based on the definition Gateways Portals Hubs Registries
37. Gateway to manage and secure the API infrastructure component highly configurable governed by guidelines and automated deployments
38. Portal stands beside the gateway as a separate component also one portal for several gateways can possible Configuration should be also be done by separate pipeline
39. Hub on a higher level than the portal acts more like a umbrella for complex infrastructure is the first step towards an internal developer platform
40. Registry stores artifacts like API definitions similar to schema registry we know supports again the idea of an internal developer platform but more technical
42. Wrap Up https://linktr.ee/danielkocot
43. Q&A
44. Thank you