Moonwalk the OpenAPI talk. Developer Experience and OpenAPI 4

Slide 1

Slide 1 text

Oleg Nenashev Lead Developer Advocate, Gradle December 3, 4 & 5, 2024 Moonwalk the OpenAPI talk Developer Experience and OpenAPI 4

Slide 2

Slide 2 text

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

Slide 3

Slide 3 text

Who uses OpenAPI? EVERYOOOONE!!!

Slide 4

Slide 4 text

APIDays 2023: OpenAPI Extensibility https://speakerdeck.com/onenashev/

Slide 5

Slide 5 text

5 github.com/OAI/moonwalk Developer Productivity and OpenAPI 4

Slide 6

Slide 6 text

Disclaimer ● I am an OpenAPI user/developer, not a core contributor ● I am sharing an outsider perspective, and not an ofﬁcial opinion ● Kudos to the OpenAPI team for reviews and feedback (this is v2)! ● Happy to be wrong ● The OpenAPI roadmap is driven by contributors, you’re welcome! 6

Slide 7

Slide 7 text

Is OpenAPI a FORMAL Speciﬁcation? 7 In computer science, formal specifications are mathematically or algorithmically based techniques whose purpose are to help with the implementation of systems and software.

Slide 8

Slide 8 text

Implementing OpenAPI specs Newcomer Developers Experienced Developers

Slide 9

Slide 9 text

No content

Slide 10

Slide 10 text

WAS 10 wiremock.io/post/creating-mock-api-templates-from-openapi

Slide 11

Slide 11 text

Developer Experience Is Important

Slide 12

Slide 12 text

12 Developer Productivity Engineering (DPE)

Slide 13

Slide 13 text

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

Slide 14

Slide 14 text

14 https://gradle.org

Slide 15

Slide 15 text

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

Slide 16

Slide 16 text

Example: OpenAPI Generator 16 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 17

Slide 17 text

We leverage OpenAPI in Develocity, too 17

Slide 18

Slide 18 text

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

Slide 19

Slide 19 text

For many FOSS projects: we sponsor Develocity licenses/hosting API for integration and developer pipelines Maven, Bazel and sbt users welcome! gradle/develocity-oss-projects gradle/develocity-oss-projects

Slide 20

Slide 20 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 20

Slide 21

Slide 21 text

21 https://gradle.com/develocity/

Slide 22

Slide 22 text

Too Many Cross-References??? 22 * it is not product placement

Slide 23

Slide 23 text

23 x.com/dastbe/status/1303858170155081728

Slide 24

Slide 24 text

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

Slide 25

Slide 25 text

25 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 26

Slide 26 text

Interoperability and Interfaces are the Key 26

Slide 27

Slide 27 text

APIs are the Key for Developer Productivity 27 response request Client App Server HTTP/2 Storage response request API API

Slide 28

Slide 28 text

API specs API tech

Slide 29

Slide 29 text

Slide 30

Slide 30 text

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

Slide 31

Slide 31 text

31 31 https://apis.guru/

Slide 32

Slide 32 text

32 Many public APIs are 2.x or 3.0 // and that’s okay!

Slide 33

Slide 33 text

33 Wait, it’s all just Swagger? OpenAPI 3.0 2016-2021

Slide 34

Slide 34 text

34 Credits to: Darrel Miller / OAI Slack

Slide 35

Slide 35 text

Now, OpenAPI changes OpenAPI 3.1 in 2021, and beyond 35

Slide 36

Slide 36 text

36 Moving Forward With backward compatibility in mind Michael Jackson, Moonwalk

Slide 37

Slide 37 text

37 “Delivering Authentic Intelligence with OpenAPI”, Darrel Miller

Slide 38

Slide 38 text

38 “Delivering Authentic Intelligence with OpenAPI”, Darrel Miller

Slide 39

Slide 39 text

39 github.com/OAI/moonwalk OpenAPI 4

Slide 40

Slide 40 text

Disclaimer We are not yet at the point of writing a formal speciﬁcation, … We will begin writing a formal document once enough decisions have been made through ADRs that a coherent document can be structured. 40 https://github.com/OAI/sig-moonwalk

Slide 41

Slide 41 text

OpenAPI 4 “Moonwalk” Project Evolve the OpenAPI Speciﬁcation to: 1. Address limitations in OpenAPI 3.x 2. More expressive API deﬁnitions, including support for advanced use cases 3. Improve user/developer experience 4. Encourage contributions and ecosystem growth 41 https://github.com/OAI/moonwalk

Slide 42

Slide 42 text

42 https://apisyouwonthate.com/blog/openapi-v4 -project-moonwalk/ Best Explainer by Phil Sturgeon, April 2024

Slide 43

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

Slide 44

Slide 44 text

44 Proper Data Nesting OpenAPI 4

Slide 45

Slide 45 text

Support different responses/actions Parameterization: ● Query parameters ● Headers ● Body 45

Slide 46

Slide 46 text

Broader range of URL Design Patterns ● “hey there’s a standard for that, let’s use it!” ● Moonwalk to be compliant with the URI RFC ○ https://datatracker.ietf.org/doc/html/rfc3986 46

Slide 47

Slide 47 text

Look at OpenAPI from the Earth ● Sporadic activity in the SIG Moonwalk repo ● No signal from June 2024? Not exactly ● Chat and meetings remain active 47 Chandrayaan-3: https://timesofindia.indiatimes.com/india/chandrayaan-3-no-signal-from-vikram-pragya n-yet-can-wait-entire-lunar-day-says-isro-chief/articleshow/103892424.cms

Slide 48

Slide 48 text

Moonwalk is a Path not a destination (milestone) 48 Source: https://www.pinterest.com/pin/1650 14773818878116/

Slide 49

Slide 49 text

Path to Moonwalk (unofﬁcial) ● No more 4.0. big bang in 2024/2025 ● Some features to land in OpenAPI 3.x ○ 3.2 (soon) - Quality of Life patches ○ 3.3 (late 2025) - larger scale topics, parameter styles, schemas/etc. ● Plans depend on the contributor availability, help needed! 49 Credits to: Henry Andrews #spec on the OAI Slack

Slide 50

Slide 50 text

Is YAML a good idea? Modeling Language != Programming Language 50

Slide 51

Slide 51 text

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

Slide 52

Slide 52 text

52 YAML DevX

Slide 53

Slide 53 text

OpenAPI is not DRY

Slide 54

Slide 54 text

54 And more constructive!

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

Open API as Code ● JSON/YAML extensions are not great ● OpenAPI speciﬁcations are huge and not sustainable as is ● It is an interexchange format ● 99% of specs are generated by tools ● We need OpenAPI DSLs 56

Slide 57

Slide 57 text

Extensibility? 57

Slide 58

Slide 58 text

Interoperability && Extensibility 58 at scale…

Slide 59

Slide 59 text

APIDays 2023: OpenAPI Extensibility https://speakerdeck.com/onenashev/

Slide 60

Slide 60 text

Example: Develocity API 60 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 61

Slide 61 text

Example: Develocity API 61 … 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 62

Slide 62 text

Slide 63

Slide 63 text

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

Slide 64

Slide 64 text

No content

Slide 65

Slide 65 text

65 Spec Extensions Public Registry

Slide 66

Slide 66 text

Moonwalk Wishlist: Extensions Registry ● We got types and namespaces registry, great! ● Alternative API spec formats (e.g. JSON Schema) 66 spec.openapis.org/registry

Slide 67

Slide 67 text

More Extensions! ● OpenAPI 4 should include standard spec extensions ● Good area to contribute! 67

Slide 68

Slide 68 text

Where did we see “x-”tensions? ● Authorization model ● Parameter values for samples ● Feature ﬂags ● Conditions ● Stateful behavior ● … 68

Slide 69

Slide 69 text

Slide 70

Slide 70 text

API specs API tech

Slide 71

Slide 71 text

● OpenAPI Initiative Subproject ● API Workﬂow deﬁnitions ● “Stateful Behavior” 71 https://github.com/OAI/Arazzo-Specification

Slide 72

Slide 72 text

72 https://github.com/OAI/Arazzo-Specification

Slide 73

Slide 73 text

73 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 74

Slide 74 text

Contributing to Moonwalk As of March 2024, we are using the following documents and processes: ● The Initial Moonwalk Proposals launched this effort, and continue to serve as the reference point for our discussions ● Discussions: All Moonwalk ideas should start as discussions ● Architectural Design Records (ADRs) as discussions produce consensus, decisions are recorded as ADRs ● Issues should only be used to track actionable work items ● Meeting Agendas focus the discussion in our weekly calls, which are open to all and are often where we decide discussions are ready for ADRs 74

Slide 75

Slide 75 text

If you consume OpenAPI based specs 75 ● Productize API - documentation, tools, versioning and maintenance ● Keep your OpenAPI version up to date ● Push your API vendors to update specs ● Invest in [API] Developer Productivity and tooling

Slide 76

Slide 76 text

If you develop specs with OpenAPI 76 ● Contribute Back! Templates/Extensions ● Try out Moonwalk, share feedback ● Need more? OpenAPI Extensions are an engine to consider

Slide 77

Slide 77 text

OpenAPI is driven by contributors. It’s [always] a great time to participate! communityinviter.com/apps/open-api/openapi openapis.org/participate/how-to-contribute 77

Slide 78

Slide 78 text

See you at APIDays Paris? OpenAPI Track API Specs & Standards Booth 78

Slide 79

Slide 79 text

References ● These slides: https://speakerdeck.com/onenashev/ ● Moonwalk SIG: https://github.com/OAI/sig-moonwalk ● 2024 plans for Moonwalk: openapis.org/blog/2023/12/06/openapi-moonwalk-2024 ● Features Overview: apisyouwonthate.com/blog/openapi-v4-project-moonwalk 79

Slide 80

Slide 80 text

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