Moonwalk the OpenAPI talk. Developer Experience and OpenAPI 4

Swagger and OpenAPI revolutionized the API landscape and created a thriving ecosystem of developer tools, from IDEs to contract testing and no-code solutions. In our projects (WireMock, Jenkins, Testcontainers, and WireMock Cloud) we adopted OpenAPI to provide a great developer experience including automated generation of plugins, pipeline integrations, and the creation of Mock APIs directly from OpenAPI definitions. Not everything went well. OpenAPI excels at documentation but not so much for machine processing. We had to craft our own tooling, apply some AI magic to reverse engineer specifications, and build behavioral models. Most of it could have been prevented if OpenAPI v3 was more flexible and extensible.

In this talk we will discuss using OpenAPI for service modeling, also known as "mocking" and its impact on developer experience. Then, we will discuss the current limitations of OpenAPI 3 and offer a glimpse into the anticipated enhancements in OpenAPI v4 "Moonwalk," which are to be released soon.

Transcript

1. Oleg Nenashev Lead Developer Advocate, Gradle December 3, 4 & 5, 2024 Moonwalk the OpenAPI talk Developer Experience and OpenAPI 4
2. Oleg Nenashev - Online Edition @oleg_nenashev oleg-nenashev Dr. Nenashev / Mr. Jenkins Community Builder Developer Tools Hacker DevRel Consultant #RussiansAgainstPutin #StandWithUkraine
3. Who uses OpenAPI? EVERYOOOONE!!!
4. APIDays 2023: OpenAPI Extensibility https://speakerdeck.com/onenashev/
5. 5 github.com/OAI/moonwalk Developer Productivity and OpenAPI 4
6. Disclaimer • I am an OpenAPI user/developer, not a core contributor • I am sharing an outsider perspective, and not an official 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
7. Is OpenAPI a FORMAL Specification? 7 In computer science, formal specifications are mathematically or algorithmically based techniques whose purpose are to help with the implementation of systems and software.
8. Implementing OpenAPI specs Newcomer Developers Experienced Developers
10. WAS 10 wiremock.io/post/creating-mock-api-templates-from-openapi
11. Developer Experience Is Important
12. 12 Developer Productivity Engineering (DPE)
13. Developer Productivity Engineering (DPE) gradle.com/ developer-productivity-engineering
14. 14 https://gradle.org
15. Example: OpenAPI plugins for Gradle 100+ related Gradle plugins Libraries and integrations in any [modern] framework (!) OpenAPI Generator 15
16. Example: OpenAPI Generator 16 https://openapi-generator.tech/ Application Programming Interface • Automates the creation of ◦ client libraries, ◦ server stubs, ◦ API documentation, ◦ and configuration files • from an OpenAPI Spec Input: Output:
17. We leverage OpenAPI in Develocity, too 17
18. 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
19. 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
20. ◦ 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
21. 21 https://gradle.com/develocity/
22. Too Many Cross-References??? 22 * it is not product placement
23. 23 x.com/dastbe/status/1303858170155081728
24. The industry uses OpenAPI, too 24 2021 Data. Source: inform.tmforum.org/features-and-opinion/the-status-of-open-api-adoption
25. 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
26. Interoperability and Interfaces are the Key 26
27. APIs are the Key for Developer Productivity 27 response request Client App Server HTTP/2 Storage response request API API
28. API specs API tech
30. Huge Tools Ecosystem 30 https://tools.openapis.org
31. 31 31 https://apis.guru/
32. 32 Many public APIs are 2.x or 3.0 // and that’s okay!
33. 33 Wait, it’s all just Swagger? OpenAPI 3.0 2016-2021
34. 34 Credits to: Darrel Miller / OAI Slack
35. Now, OpenAPI changes OpenAPI 3.1 in 2021, and beyond 35
36. 36 Moving Forward With backward compatibility in mind Michael Jackson, Moonwalk
37. 37 “Delivering Authentic Intelligence with OpenAPI”, Darrel Miller
38. 38 “Delivering Authentic Intelligence with OpenAPI”, Darrel Miller
39. 39 github.com/OAI/moonwalk OpenAPI 4
40. Disclaimer We are not yet at the point of writing a formal specification, … 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
41. OpenAPI 4 “Moonwalk” Project Evolve the OpenAPI Specification to: 1. Address limitations in OpenAPI 3.x 2. More expressive API definitions, including support for advanced use cases 3. Improve user/developer experience 4. Encourage contributions and ecosystem growth 41 https://github.com/OAI/moonwalk
42. 42 https://apisyouwonthate.com/blog/openapi-v4 -project-moonwalk/ Best Explainer by Phil Sturgeon, April 2024
43. 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
44. 44 Proper Data Nesting OpenAPI 4
45. Support different responses/actions Parameterization: • Query parameters • Headers • Body 45
46. 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
47. 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
48. Moonwalk is a Path not a destination (milestone) 48 Source: https://www.pinterest.com/pin/1650 14773818878116/
49. Path to Moonwalk (unofficial) • 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
50. Is YAML a good idea? Modeling Language != Programming Language 50
51. Example: AWS API Gateway 51 https://swagger.io/docs/specification/v3_0/openapi-extensions
52. 52 YAML DevX
53. OpenAPI is not DRY
54. 54 And more constructive!
55. 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 55 Source: https://www.youtube.com/watch?app=desktop&v=Iiygq3r1QPs
56. Open API as Code • JSON/YAML extensions are not great • OpenAPI specifications are huge and not sustainable as is • It is an interexchange format • 99% of specs are generated by tools • We need OpenAPI DSLs 56
57. Extensibility? 57
58. Interoperability && Extensibility 58 at scale…
59. APIDays 2023: OpenAPI Extensibility https://speakerdeck.com/onenashev/
60. 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
61. 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
63. Where did we see “x-”tensions? • Authorization model • Parameter values for samples • Feature flags • Conditions • Stateful behavior • … 63 Image source: orchid-tech.com/design-notes/ fpga-complex-algorithm-development/
65. 65 Spec Extensions Public Registry
66. Moonwalk Wishlist: Extensions Registry • We got types and namespaces registry, great! • Alternative API spec formats (e.g. JSON Schema) 66 spec.openapis.org/registry
67. More Extensions! • OpenAPI 4 should include standard spec extensions • Good area to contribute! 67
68. Where did we see “x-”tensions? • Authorization model • Parameter values for samples • Feature flags • Conditions • Stateful behavior • … 68
70. API specs API tech
71. • OpenAPI Initiative Subproject • API Workflow definitions • “Stateful Behavior” 71 https://github.com/OAI/Arazzo-Specification
72. 72 https://github.com/OAI/Arazzo-Specification
73. 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
74. 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
75. 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
76. 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
77. 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
78. See you at APIDays Paris? OpenAPI Track API Specs & Standards Booth 78
79. 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
80. Gradle Slack, #developer-productivity OPENQuestions? OpenAPI Initiative Slack 80