Die OpenAPI Spezifikation – ein Standard zur Beschreibung moderner APIs

APIs spielen bei der Verbindung von Anwendungen und Workflows eine zentrale Rolle. Fast ausschließlich wird über APIs auf Datenquellen und andere Systeme zugegriffen. Durch die zunehmende Verbreitung von serviceorientierten und Microservices-Architekturen sowie der daraus folgenden Aufteilung hat die Anzahl der involvierten APIs pro Anwendungsfall zugenommen. Die OpenAPI Spezifikation hilft als offenes Beschreibungsformat dabei, den Überblick und das Verständnis über die Fähigkeiten eines API zu erhalten. Mit dieser Hilfe kann man eine effektive API-Strategie etablieren, die entscheidend für schnelle Innovationen und die digitale Transformation ist.

Die Spezifikation wird seit einiger Zeit herstellerneutral unter dem Mantel der Linux Foundation von der Open API Initiative (OAI) vorangetrieben. Diese Standardisierung und die leichtgewichtigen Definitionsmöglichkeiten im JSON- bzw. YAML-Format ermöglichen in Kombination mit Werkzeugen zahlreicher Hersteller ein durchgängiges Verständnis von der Business-Sicht bis hin zur technischen Perspektive.

Im Vortrag werden die Bestandteile der OpenAPI Spezifikation und auch Unterschiede zu anderen früheren Ansätzen, wie der Web Services Description Language (WSDL) vorgestellt. Es werden mit Contract/ API First und Code First die zwei grundlegenden Vorgehen beim API-Design erläutert. Zuletzt wird auf das Thema API-Management eingegangen, d.h. wie kann bspw. eine Vielzahl von APIs in mehreren parallelen Versionen verwaltet werden und außerdem Zuverlässigkeit und Sicherheit gewährleistet werden.

Transcript

1. WORKFLOW ANALYTICA 2022 - DIE OPENAPI SPEZIFIKATION © 2022, Amazon Web Services, Inc. or its affiliates. © 2022, Amazon Web Services, Inc. or its affiliates. Die OpenAPI Spezifikation Ein Standard zur Beschreibung moderner APIs Dennis Kieselhorst Sr. Solutions Architect Amazon Web Services
2. WORKFLOW ANALYTICA 2022 - DIE OPENAPI SPEZIFIKATION © 2022, Amazon Web Services, Inc. or its affiliates. © 2022, Amazon Web Services, Inc. or its affiliates. Motivation • Processes and IT landscapes are becoming more and more complex. • Modern architecture approaches like Microservices bring a lot of benefits but also increase the complexity. • It’s challenging to document dependencies and interactions, manual documentation often gets outdated. How to maintain an overview?
3. WORKFLOW ANALYTICA 2022 - DIE OPENAPI SPEZIFIKATION © 2022, Amazon Web Services, Inc. or its affiliates. Application Programming Interfaces (APIs) • Simplify programming by abstracting the underlying implementation and only exposing objects or actions needed. • APIs are the „glue“ between applications. Client(s) API Web Server Database Request Response
4. WORKFLOW ANALYTICA 2022 - DIE OPENAPI SPEZIFIKATION © 2022, Amazon Web Services, Inc. or its affiliates. © 2022, Amazon Web Services, Inc. or its affiliates. API Mandate at Amazon 1. All teams will henceforth expose their data and functionality through service interfaces. 2. Teams must communicate with each other through these interfaces. 3. There will be no other form of inter-process communication allowed. 4. It doesn’t matter what technology they use. 5. All service interfaces, without exception, must be designed from the ground up to be externalizable. Conway’s Law: Organizations design systems that model the organization and communication structure
5. WORKFLOW ANALYTICA 2022 - DIE OPENAPI SPEZIFIKATION © 2022, Amazon Web Services, Inc. or its affiliates. How to describe APIs? - The Open API Initiative • The Web Services Description Language (WSDL) was famous but not resource-oriented. • Swagger was born in 2010 as an interface definition language (IDL) for REST-APIs with a fast-growing fan community. • End of 2015 the Open API Initiative (OAI) under the umbrella of the Linux Foundation was formed (currently 44 members). • Swagger was renamed to OpenAPI Specification (OAS). ▪ The old name is still used for tooling. ▪ Further spec development happens on GitHub. ▪ In July 2017 the new major version 3.0.0 was published, the release of the latest version 3.1.0 happened in February 2021.
6. WORKFLOW ANALYTICA 2022 - DIE OPENAPI SPEZIFIKATION © 2022, Amazon Web Services, Inc. or its affiliates. Contract/ API-First vs. Code First approach Contract/ API-First Specification is defined first and acts as service contract • helpful for different teams on client-/ server side • even more across different companies/ with third parties Client- and servercode can be generated with a code generator • ensures code is always consistent to the API • compile errors for breaking changing (possible to automate using Continious Integration tool) • code is not as clean as handwritten code, may look confusing • tolerant reader pattern may be a better option over spec-based code generation (depends on the scope and change frequency of the API) Code First Specification is derived from API implementation • code can be annotated • export is either done at compile or runtime (e.g. using /openapi.yaml http call) • developers are familiar with it → fast for simple APIs Generated specification may contain unused resources • easily happens that something is accidently exposed • often lack of documentation
7. WORKFLOW ANALYTICA 2022 - DIE OPENAPI SPEZIFIKATION © 2022, Amazon Web Services, Inc. or its affiliates. © 2022, Amazon Web Services, Inc. or its affiliates. Tool support for OpenAPI development • Low-level tooling • generic libraries • e.g. parser/ validator • Editors • User interfaces • Mock servers/ testing tools • Client and server implementations • Code generators
8. WORKFLOW ANALYTICA 2022 - DIE OPENAPI SPEZIFIKATION © 2022, Amazon Web Services, Inc. or its affiliates. OpenAPI document structure OpenAPI 3 components paths webhooks info servers security tags externalDocs components schemas responses parameters examples requestBodies headers securitySchemes links callbacks pathItems
9. WORKFLOW ANALYTICA 2022 - DIE OPENAPI SPEZIFIKATION © 2022, Amazon Web Services, Inc. or its affiliates. © 2022, Amazon Web Services, Inc. or its affiliates. Demo
10. WORKFLOW ANALYTICA 2022 - DIE OPENAPI SPEZIFIKATION © 2022, Amazon Web Services, Inc. or its affiliates. Creating/ editing an OpenAPI definition
11. WORKFLOW ANALYTICA 2022 - DIE OPENAPI SPEZIFIKATION © 2022, Amazon Web Services, Inc. or its affiliates. Importing an OpenAPI definition
12. WORKFLOW ANALYTICA 2022 - DIE OPENAPI SPEZIFIKATION © 2022, Amazon Web Services, Inc. or its affiliates. Managing API stages/ versioning of APIs 12
13. WORKFLOW ANALYTICA 2022 - DIE OPENAPI SPEZIFIKATION © 2022, Amazon Web Services, Inc. or its affiliates. Trigger an API from a workflow
14. WORKFLOW ANALYTICA 2022 - DIE OPENAPI SPEZIFIKATION © 2022, Amazon Web Services, Inc. or its affiliates. API Gateway AWS Step Functions workflow API Gateway API Gateway EventBridge event bus SNS topic Rule Mobile client Mobile client 100s – 1,000,000s Rule Workflow EventBridge event bus Rule SQS queue Lambda function Rule API Gateway Application load balancer Event-driven architecture example
15. WORKFLOW ANALYTICA 2022 - DIE OPENAPI SPEZIFIKATION © 2022, Amazon Web Services, Inc. or its affiliates. © 2022, Amazon Web Services, Inc. or its affiliates. Summary • APIs help to control the data flow. • Designing an API specification (contract) is a critical step. • Ensure ownership for each API by setting up a proper team structure. • OpenAPI is well supported by tools and frameworks. • Serverless services for API development and management simplify the process and increase agility.
16. WORKFLOW ANALYTICA 2022 - DIE OPENAPI SPEZIFIKATION © 2022, Amazon Web Services, Inc. or its affiliates. Thank you! © 2022, Amazon Web Services, Inc. or its affiliates. Dennis Kieselhorst linkedin.com/in/kieselhorst/