The state of #OpenAPI

* Generators for 5 of the top 20 most popular programming languages have wild variations in features supported, and *usually* interpret common features differently.
* Two of the 5 language's client generators produce code which require manual modifications before it will compile or behave as intended.
* Automatic generation server-side is still limited.
* The latest *minor* update, released 5 years ago, only has *experimental* support in most tooling.

Implementing Zalando RESTful API Guidelines with Quarkus https://myfear.substack.com/p/implementing-zalando-restful-api
#Java #Quarkus #OpenAPI #Zalando

Join me at DevFest Pisa 2025 where I’ll be sharing insights on how to elevate API experiences!

My talk, “Overlay and Arazzo: From API Definitions to API Experiences” will explore how we can transform APIs into seamless user experiences.

When: April 12, 2025
Time: 11:40 AM
Where: MACC - Pisa - Italy
Schedule: https://devfest.gdgpisa.it/talk/overlay-and-arazzo-from-api-definitions-to-api-experiences/

Hope to see you there!

Spec-First or Code-First? Choosing Your OpenAPI Strategy with Quarkus vs. Spring https://myfear.substack.com/p/spec-first-or-code-first-choosing
#Java #Quarkus #APIDesign #OpenAPI

"The accompanying diagram is intended to help you quickly decide how to document an API, but particularly a REST API. The first split is just to make sure you are looking for the right kind of API.

Here is some more context to help you decide on an approach and get started."

https://gist.github.com/briandominick/3ffab6be460fbde799aa34e0a42a4299

Today I added #OpenAPI documentation to #dweb for building #RESTful #p2p web apps using your favourite web framework, or no framework at all.

All I have to do now is add more APIs!

But tbh, that's easy. The hardest part is actually the documentation.

So to make it more fun I'm adding the APIs need to enhance my #Fileman #Svelte demo.

So next is image preview which means adding /dweb-0/file-get

Change the fields returned by your API by offering more representations of the resources. This under-appreciated feature of API design can help teams to get the best from their API for multiple use cases, without the need to switch to GraphQL.

https://lornajane.net/posts/2025/better-rest-before-graphql

Having played a bit I'm now adding #OpenAPI docs with #Swagger UI to #Autonomi dweb using #utoipa and #utoipauto.

EDIT: switched from #utoipauto to #utoipa_actix_web

I'm neither a user nor, until now a builder of HTTP APIs so stumbling around, but these crates do a decent job of being usable even to a novice.

I really shouldn't be let loose with all this

Baby steps building my first #REST API into #dweb using #actix and now wondering how to document it.

First impression is #utoipa (more active and possibly suitable than #apisto) so I'll try the former first.

Opinions and experiences with these and other options welcome!
#OpenAPI #Rustlang

【Hono】作成したAPIをSwagger UI上で動作確認したい
https://qiita.com/ryouryou_34/items/a5b566e0feb6457275cb?utm_campaign=popular_items&utm_medium=feed&utm_source=popular_items

Unlock the Power of Your APIs: A Hands-On Introduction to Quarkus OpenAPI with Swagger
Effortless API Documentation in Quarkus: Getting Started with OpenAPI
https://open.substack.com/pub/myfear/p/unlock-the-power-of-your-apis-a-hands
#Quarkus #Java #OpenAPI #Swagger #API

Hey, folks! I’m looking for a Staff Software Engineer to join my team (API Core) at #Mailchimp.

Some of the things we work on: #PHP, #REST, #OpenAPI, #OAuth2, #APIGovernance, and more.

We are stewards of our public #APIs, and we collaborate with other capabilities teams to ensure APIs are developed according to our standards and processes. You would work directly with me on a daily basis.

This position is in Atlanta or New York.

https://jobs.intuit.com/job/atlanta/staff-software-engineer-api-core-team/27595/76329932512

It's my first open source release in what feels like years, but I've published a new #PHP library for parsing #openapi Arazzo specifications into plain old PHP objects. I'm hoping to use this as the starting point for future #arazzo related packages, and looking forward to seeing what others may build with it.

https://github.com/hskrasek/arazzo-parser/

API reference documentation changed the way we built integrations, and eventually became part of the driving force for OpenAPI adoption and all the good tooling that flowed from it. As a developer experience specialist, I spend a lot of time thinking about how human users can work with the technical assets in a project. HTML-format API reference documentation does a great job of building that bridge when working on OpenAPI projects, but now I’m using Arazzo and it’s a very new standard with not nearly as many tools available for that format yet – so I built one. […]

https://lornajane.net/posts/2025/markdown-mermaid-output-for-openapi-arazzo

Got completely carried away writing what was supposed to be a simple article on #OpenAPI linting and now I'm deep in Vacuum, Scalar, and Microcks features and it's GREAT. How's your Tuesday?

I’ve recently taken a closer look at the #Foursquare #API (updating the long unmaintained Platypush plugin, details on why coming soon).

At first their new API versioning schema seemed a bit confusing (why would anyone use arbitrary YYYYMMDD strings as versions?), but a closer look at how they implemented it revealed a quite clever design decision:

Versioning is controlled by the v parameter, which is a date that represents the “version” of the API for which you expect from Foursquare. It is designed to give developers the freedom to adapt to Foursquare API changes on their own schedule. The value of the v parameter is a date in YYYYMMDD format that lets you tell us “I’m prepared for API changes up to this date.”

You know when you look at an engineering decision that is so elegant and obvious that you think “damn, how could nobody think of this before?”

Nearly two decades spent managing /v1, /v2, /v2.5, /v2.almost3, /v3, managing migrations and deprecations, documenting breaking changes, introducing exponentially thicker layers of schemas and converters, and the obvious solution was just there under our nose.

Why don’t you just start with defining the base schemas of your API objects at the time of their first release, and then every time you add, modify or delete a field, or change some return type, or add a value to an enum, you just version the change with a timestamp?

Let the developer say “I understand the language that your API spoke 3 months ago”, and you just dynamically create the schemas, GraphQL or ORM snippets to parse requests and responses as of that date.

No more breaking changes. No more forced migrations. No more boilerplate to explicitly convert payloads across different API versions.

You construct the response by first applying the base schema, and then gradually patching it - just like you would do with a git rebase, or an ORM migration tool.

A downside may probably be that you can never really delete a column from the db if it was ever used by any version of your API.

And a challenge may also be to adapt tools like #OpenAPI / #Swagger that were designed around static schemas to also work with “dynamically versioned” selections.

But to me the problems it solves far outweight the downsides.

https://docs.foursquare.com/developer/reference/versioning

https://github.com/lil5/ledgerbeetle/commit/ad9c85f14d7094c70d7712ba4f327526fea26641

https://crates.io/crates/utoipa

I started using utopia to generate the #OpenAPI document, its great!

A coalition of European cloud providers, including Aruba, IONOS and Dynamo, has introduced the Sovereign European Cloud API (SECA), a new open standard for cloud infrastructure management.

https://www.computing.co.uk/news/2025/cloud/european-cloud-providers-push-for-open-api-standard-amid-sovereignty-concerns

I think I’ll switch the Keila API docs (https://app.keila.io/api) from Swagger to Scalar. It just looks much cleaner and more professional.

Any Phoenix devs who have done this already with Open API Spex?