OpenAPI: The Good, The Bad, The YAMLy - Gradle Edition

Slide 1

Slide 1 text

OpenAPI Extensibility Oleg Nenashev, Baruch Sadogursky, Laura Kassovic The Good, The Bad, The YAMLy

Slide 2

Slide 2 text

No content

Slide 3

Slide 3 text

Oleg Nenashev - Online Edition @oleg_nenashev oleg-nenashev Dr. Nenashev / Mr. Jenkins Community Builder Developer Tools Hacker DevRel Consultant (#OpenToWork) #RussiansAgainstPutin #StandWithUkraine

Slide 4

Slide 4 text

Online Edition :( 4 Various API calls

Slide 5

Slide 5 text

Baruch Sadogursky - In-Person Edition @jbaruch jbaruch Developer Productivity Advocate DevRel Advisor @Gradle Java Champion CNCF Ambassador Alumni

Slide 6

Slide 6 text

Laura Kassovic - In-Person Edition Technical Writer Community Builder Open Source Advocate Documentation First Approach lkasso

Slide 7

Slide 7 text

Slides&Links: https://speakerdeck.com/onenashev/ Nov 06 Video: https://speaking.jbaru.ch/

Slide 8

Slide 8 text

8 Developer Productivity Engineering (DPE)

Slide 9

Slide 9 text

Developer Productivity Engineering (DPE) gradle.com/ developer-productivity-engineering

Slide 10

Slide 10 text

10 x.com/dastbe/status/1303858170155081728

Slide 11

Slide 11 text

11 The UNIX way Peter H. Salus, A Quarter-Century of Unix (1994) ● 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

Slide 12

Slide 12 text

Interoperability and Interfaces are the Key 12

Slide 13

Slide 13 text

Most Apps and Dev Tools Work with APIs 13 response request Client App Server HTTP/2 Storage response request API API

Slide 14

Slide 14 text

API specs API tech

Slide 15

Slide 15 text

Slide 16

Slide 16 text

No content

Slide 17

Slide 17 text

No content

Slide 18

Slide 18 text

18 OpenAPI 101 Request-Response deﬁnitions Parameters Response samples Extensions

Slide 19

Slide 19 text

Huge Tools Ecosystem 19 https://tools.openapis.org

Slide 20

Slide 20 text

Example: OpenAPI plugins for Gradle 100+ related Gradle plugins Libraries and integrations in any [modern] framework (!) OpenAPI Generator 20

Slide 21

Slide 21 text

Who uses OpenAPI? EVERYOOOONE!!!

Slide 22

Slide 22 text

The industry uses OpenAPI, too 22 2021 Data. Source: inform.tmforum.org/features-and-opinion/the-status-of-open-api-adoption

Slide 23

Slide 23 text

We leverage OpenAPI in Develocity, too 23

Slide 24

Slide 24 text

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

Slide 25

Slide 25 text

Example: OpenAPI Generator 25 https://openapi-generator.tech/ Application Programming Interface ● Automates the creation of ○ client libraries, ○ server stubs, ○ API documentation, ○ and conﬁguration ﬁles ● from an OpenAPI Spec Input: Output:

Slide 26

Slide 26 text

● ○ Build Scan and Troubleshooting ○ Local and Distributed build caching ○ Predictive Test Selection ○ CI/CD observability and Insights ○ Local build observability Public Develocity Instance: ge.openapi-generator.tech We support OpenAPI Generator 26

Slide 27

Slide 27 text

● We support open source ● Many projects run with Develocity ● Maven, Bazel, sbt.., and Gradle gradle/develocity-oss-projects

Slide 28

Slide 28 text

Huge Tools Ecosystem (RECAP) 28 https://tools.openapis.org

Slide 29

Slide 29 text

Interoperability && Extensibility 29 at scale…

Slide 30

Slide 30 text

30 OpenAPI 101 Request-Response deﬁnitions Parameters Response samples Extensions

Slide 31

Slide 31 text

OpenAPI Extensions github.com/OAI/OpenAPI-Speciﬁcation/blob/main/guidelines/v2.0/EXTENSIONS.md 31 spec.openapis.org/oas/latest.html#specification-extensions

Slide 32

Slide 32 text

OpenAPI Extensions 101 32 https://github.com/OAI/OpenAPI-Specification/blob /main/guidelines/v2.0/EXTENSIONS.md

Slide 33

Slide 33 text

Example: Develocity API 33 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 docs.gradle.com/develocity/api-manual/ #reference_documentation

Slide 34

Slide 34 text

Example: Develocity API 34 … 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. docs.gradle.com/develocity/api-manual/ #reference_documentation

Slide 35

Slide 35 text

Slide 36

Slide 36 text

No content

Slide 37

Slide 37 text

Example: AWS API Gateway 37 https://swagger.io/docs/specification/v3_0/openapi-extensions

Slide 38

Slide 38 text

38 YAML DevX

Slide 39

Slide 39 text

OpenAPI is not DRY

Slide 40

Slide 40 text

40 And more constructive!

Slide 41

Slide 41 text

No content

Slide 42

Slide 42 text

No content

Slide 43

Slide 43 text

43 Wait, it’s all just Swagger? OpenAPI 3 Extensions

Slide 44

Slide 44 text

So, but what’s ugly? ● Limited v3 Documentation, mostly inherited from Swagger ● Little updates and docs before late 2023 ● Little “extension specs” 44

Slide 45

Slide 45 text

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? 45 Image source: dev.to/meatboy/what-are-modern-examples-of-embrace-extend-and-extinguish-21j3

Slide 46

Slide 46 text

46 Source: https://medium.com/10-minutes-qa-story/api-testing-from-scratch-api-anatomy-f220856ce9b3

Slide 47

Slide 47 text

Extensions are for lock-in ● Most specs are generated by tools, they leverage extensions ● JSON/YAML extensions are not great to manage ● OpenAPI speciﬁcations are huge and not sustainable as is ● OpenAPI but with SDKs 47

Slide 48

Slide 48 text

Where did we see “x-”tensions? ● Authorization model ● Parameter values for samples ● Feature ﬂags ● Conditions ● Stateful behavior ● … 48 Image source: orchid-tech.com/design-notes/ fpga-complex-algorithm-development/

Slide 49

Slide 49 text

No content

Slide 50

Slide 50 text

No content

Slide 51

Slide 51 text

51 github.com/OAI/moonwalk OpenAPI 4

Slide 52

Slide 52 text

OpenAPI 4 “Moonwalk” Project Evolve the OpenAPI Speciﬁcation to: 1. Address limitations in the existing OpenAPI 3.x versions 2. Introduce features that allow for more expressive API deﬁnitions, including support for advanced use cases 3. Improve user experience 4. Encourage contributions and community feedback 52 https://github.com/OAI/moonwalk

Slide 53

Slide 53 text

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 53 https://github.com/OAI/moonwalk

Slide 54

Slide 54 text

OpenAPI 4 “Moonwalk” Wishlist: Extensions Registry ● OpenAPI 4 should include standard spec extensions ● From x-logo to x-auth 54

Slide 55

Slide 55 text

OpenAPI 4 “Moonwalk” Wishlist: Overlay Speciﬁcations 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 55 Source: https://www.youtube.com/watch?app=desktop&v=Iiygq3r1QPs

Slide 56

Slide 56 text

See you at APIDays Paris? Speaking on Developer Experience and Project Moonwalk: ● “Walk the OpenAPI Talk, Moonwalk the DevEx!” ● Dec 03, 11:00, OpenAPI Track API Specs & Standards Booth 56

Slide 57

Slide 57 text

57 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 PLEASE MAKE IT HAPPEN

Slide 58

Slide 58 text

If you develop OpenAPI Specs 58 ● Need more? OpenAPI Extensions are an engine to consider ● Extensions help where the speciﬁcation does not ● Try out Moonwalk, share feedback

Slide 59

Slide 59 text

If you consume OpenAPI Specs 59 ● Productize API - documentation, tools, versioning and maintenance ● Keep your OpenAPI version up to date ● Document / Share your extensions

Slide 60

Slide 60 text

Gradle Slack, #developer-productivity OPENQuestions? OpenAPI Initiative Slack 60