OpenAPI Extensibility - The Good, The Bad and The YAMLy

OpenAPI Extensibility The Good, The Bad, The YAMLy Oleg Nenashev, Baruch Sadogursky, Laura Kassovic #DPE #ApiWorld https://speaking.jbaru.ch

#DPE #ApiWorld https://speaking.jbaru.ch

Baruch Sadogursky Developer Productivity Advocate DevRel Advisor @Gradle Java Champion CNCF Ambassador Alumni @jbaruch jbaruch #DPE #ApiWorld https://speaking.jbaru.ch

Laura Kassovic Technical Writer Community Builder Open Source Advocate lkasso #DPE #ApiWorld https://speaking.jbaru.ch

Oleg Nenashev - Online Edition Dr. Nenashev / Mr. Jenkins Community builder Developer Tools Hacker @oleg_nenashev oleg-nenashev #DPE #RussiansAgainstPutin #StandWithUkraine #ApiWorld https://speaking.jbaru.ch

Shownotes ● speaking.jbaru.ch ● Slides ● All the links! ● Video #DPE #ApiWorld https://speaking.jbaru.ch 6

Developer Productivity Engineering (DPE) 7 #DPE #ApiWorld https://speaking.jbaru.ch

Developer Productivity Engineering (DPE) gradle.com/ developer-productivity-engineering #DPE #ApiWorld https://speaking.jbaru.ch

9 #DPE #ApiWorld https://speaking.jbaru.ch x.com/dastbe/status/1303858170155081728

The UNIX way ● Write programs that DO ONE THING and DO IT WELL ● Write programs to WORK TOGETHER ● Write programs to handle text streams, because that is a UNIVERSAL INTERFACE Peter H. Salus, A Quarter-Century of Unix (1994) #DPE #ApiWorld https://speaking.jbaru.ch 10

Interoperability and Interfaces are the Key #DPE #ApiWorld https://speaking.jbaru.ch 11

Most Apps and Dev Tools Work with APIs Client App #DPE request request response response HTTP/2 API API Server #ApiWorld Storage https://speaking.jbaru.ch 12

API specs #DPE API tech #ApiWorld https://speaking.jbaru.ch

#DPE #ApiWorld https://speaking.jbaru.ch 14

#DPE #ApiWorld https://speaking.jbaru.ch

OpenAPI 101 Request-Response definitions Parameters Response samples Extensions #DPE #ApiWorld https://speaking.jbaru.ch 17

Huge Tools Ecosystem #DPE #ApiWorld https://tools.openapis.org https://speaking.jbaru.ch 18

Example: OpenAPI plugins for Gradle 100+ related Gradle plugins Libraries and integrations in any [modern] framework (!) OpenAPI Generator #DPE #ApiWorld https://speaking.jbaru.ch 19

Who uses OpenAPI? EVERYOOOONE!!! #DPE #ApiWorld https://speaking.jbaru.ch

The industry uses OpenAPI, too #DPE #ApiWorld https://speaking.jbaru.ch 2021 Data. Source: inform.tmforum.org/features-and-opinion/the-status-of-open-api-adoption 21

We leverage OpenAPI in Develocity, too #DPE #ApiWorld https://speaking.jbaru.ch 22

Example: Develocity ● Not just OpenAPI, but an API Manual ○ https://docs.gradle.com/develocity/api-manual ● Versioning and Depreciation policy via OpenAPI annotations ● User-friendly changelogs #DPE #ApiWorld https://speaking.jbaru.ch 23

Application Programming Interface Example: OpenAPI Generator ● Automates the creation of ○ ○ ○ ○ Input: Output: client libraries, server stubs, API documentation, and configuration files ● from an OpenAPI Spec https://openapi-generator.tech/ #DPE #ApiWorld https://speaking.jbaru.ch 24

We support OpenAPI Generator ● ○ Build Scan and Troubleshooting ○ Local and Distributed build caching ○ Predictive Test Selection ○ CI/CD observability and Insights ○ Local build observability #DPE #ApiWorld Public Develocity Instance: ge.openapi-generator.tech https://speaking.jbaru.ch 25

● We support open source ● Many projects run with Develocity ● Maven, Bazel, sbt.., and Gradle gradle/develocity-oss-projects #DPE #ApiWorld https://speaking.jbaru.ch

Huge Tools Ecosystem (RECAP) #DPE #ApiWorld https://tools.openapis.org https://speaking.jbaru.ch 27

Interoperability && Extensibility #DPE at scale… #ApiWorld https://speaking.jbaru.ch 28

OpenAPI 101 Request-Response definitions Parameters Response samples Extensions #DPE #ApiWorld https://speaking.jbaru.ch 29

OpenAPI Extensions 101 https://github.com/OAI/OpenAPI-Specification/blob /main/guidelines/v2.0/EXTENSIONS.md #DPE #ApiWorld https://speaking.jbaru.ch 30

OpenAPI Extensions github.com/OAI/OpenAPI-Specification/blob/main/guidelines/v2.0/EXTENSIONS.md #DPE spec.openapis.org/oas/latest.html#specification-extensions #ApiWorld https://speaking.jbaru.ch 31

Example: Develocity API docs.gradle.com/develocity/api-manual/ #reference_documentation openapi: 3.0.3 info: title: Develocity API description: > Allows programmatic interaction with Develocity, from config to build data version: “2024.2” license: name: Develocity License url: https://gradle.com/legal-gradle-software-license-agreement termsOfService: https://gradle.com/help/legal-terms-of-use x-logo: url: https://assets.gradle.com/logo/develocity-logo.svg altText: Develocity #DPE #ApiWorld https://speaking.jbaru.ch 32

Example: Develocity API … docs.gradle.com/develocity/api-manual/ #reference_documentation tags: - name: BuildCache x-displayName: Build Cache description: | Endpoints related to configuring the Build Cache nodes of the Develocity instance. To access these endpoints the user requires the Configure build caches permission. - name: Projects x-displayName: Projects (Beta) description: | Endpoints related to the management of projects in Develocity. To access these endpoints the user requires the Administer Projects permission. #DPE #ApiWorld https://speaking.jbaru.ch 33

#DPE #ApiWorld https://speaking.jbaru.ch 34

#DPE #ApiWorld https://speaking.jbaru.ch

Example: AWS API Gateway #DPE https://swagger.io/docs/specification/v3_0/openapi-extensions #ApiWorld https://speaking.jbaru.ch 36

YAML DevX #DPE #ApiWorld https://speaking.jbaru.ch 37

OpenAPI is not DRY #DPE #ApiWorld https://speaking.jbaru.ch

And more constructive! 39 #DPE #ApiWorld https://speaking.jbaru.ch

#DPE #ApiWorld https://speaking.jbaru.ch

Wait, it’s all just Swagger? OpenAPI 3 Extensions #DPE #ApiWorld https://speaking.jbaru.ch 42

So, but what’s ugly? ● Limited v3 Documentation, mostly inherited from Swagger ● Little updates and docs before late 2023 ● Little “extension specs” #DPE #ApiWorld https://speaking.jbaru.ch 43

Specification is an inspiration ● Nobody cares where “x-” fields are supported or not ● Almost everything in “x-” fields? Why not ● Encrypted data in spec? Data blobs? Why not? ● Contribute back? Why? #DPE #ApiWorld Image source: dev.to/meatboy/what-are-modern-examples-of-embrace-extend-and-extinguish-21j3 https://speaking.jbaru.ch 44

#DPE Source: https://medium.com/10-minutes-qa-story/api-testing-from-scratch-api-anatomy-f220856ce9b3 #ApiWorld https://speaking.jbaru.ch 45

Extensions are for lock-in ● Most specs are generated by tools, they leverage extensions ● JSON/YAML extensions are not great to manage ● OpenAPI specifications are huge and not sustainable as is ● OpenAPI but with SDKs #DPE #ApiWorld https://speaking.jbaru.ch 46

Where did we see “x-”tensions? ● Authorization model ● Parameter values for samples ● Feature flags ● Conditions ● Stateful behavior ● … #DPE #ApiWorld Image source: orchid-tech.com/design-notes/ fpga-complex-algorithm-development/ https://speaking.jbaru.ch 47

#DPE #ApiWorld https://speaking.jbaru.ch

OpenAPI 4 github.com/OAI/moonwalk #DPE #ApiWorld https://speaking.jbaru.ch 50

OpenAPI 4 “Moonwalk” Project Evolve the OpenAPI Specification to: 1. Address limitations in the existing OpenAPI 3.x versions 2. Introduce features that allow for more expressive API definitions, including support for advanced use cases 3. Improve user experience 4. Encourage contributions and community feedback #DPE #ApiWorld https://github.com/OAI/moonwalk https://speaking.jbaru.ch 51

OpenAPI 4 “Moonwalk” Features ● Support APIs that have different responses based on query parameters, headers and request bodies. ● Broader range of URL design patterns ● Reduce nested structures to improve readability and editability ● Improve reusability of request and response patterns #DPE #ApiWorld https://github.com/OAI/moonwalk https://speaking.jbaru.ch 52

OpenAPI 4 “Moonwalk” Wishlist: Extensions Registry ● OpenAPI 4 should include standard spec extensions ● From x-logo to x-auth #DPE #ApiWorld https://speaking.jbaru.ch 53

OpenAPI 4 “Moonwalk” Wishlist: Overlay Specifications to become a part of the standard aka “openapi-patch” injecting duplicated content into the specs spec.openapis.org/ove rlay/v1.0.0.html Source: https://www.youtube.com/watch?app=desktop&v=Iiygq3r1QPs #DPE #ApiWorld https://speaking.jbaru.ch 54

PLEASE MAKE IT HAPPEN #DPE #ApiWorld https://speaking.jbaru.ch Source: https://www.businesstoday.in/visualstories/news/will-boeings-starliner-failures-impact-nasas-artemis-3-moon-landing-similar-to-sunita-williams-space-stranding-161968-12-08-2024 55

If you develop OpenAPI Specs ● Need more? OpenAPI Extensions are an engine to consider ● Extensions help where the specification does not ● Try out Moonwalk, share feedback #DPE #ApiWorld https://speaking.jbaru.ch 56

If you consume OpenAPI Specs ● Productize API - documentation, tools, versioning and maintenance ● Keep your OpenAPI version up to date ● Document / Share your extensions #DPE #ApiWorld https://speaking.jbaru.ch 57

OPENQuestions? OpenAPI Initiative Slack Gradle Slack, #developer-productivity #DPE #ApiWorld https://speaking.jbaru.ch 58