mastodon.world is one of the many independent Mastodon servers you can use to participate in the fediverse.
Generic Mastodon server for anyone to use.

Server stats:

8.5K
active users

#openapi

7 posts7 participants0 posts today

Is there any best practice for how to document authorization on specific endpoints within #openapi documentation? f.e. if an endpoint requires a specific user role. it does not seem to be covered within the spec itself, that only seems to be dealing with authentication.

Introducing: BinkyLabs.OpenApi.Overlay a new library to parse and apply OpenAPI overlays in #dotnet !!! 🎉🎉🎉🎉

github.com/BinkyLabs/openapi-o

Over the last week, a good friend of mine Matthieu COSTABELLO and I have been hacking away to produce this new library. It's modeled after Microsoft.OpenAPI, parses, serializes and applies overlays to documents.

With overlays, you can maintain patches to #OpenAPI description, extremely useful when your team doesn't "own" the document but needs to maintain only a few changes. Using this library, a host of OpenAPI tools built in #dotnet will be able to support this specification and new feature!

Stay tuned for more projects from BinkyLabs!

Системное мышление: когда разработчик становится архитектором

Что отличает архитектора от кодера? Не должность, не титул, не стаж. Ответ - в мышлении. В том, кто видит систему целиком, предвидит цепные последствия и способен сказать "нет" быстрому решению, которое отравит код через полгода. Эта статья - честное и местами болезненное размышление о системном мышлении, архитектуре и точке невозврата, после которой разработчик уже не может смотреть на код по-старому.

habr.com/ru/articles/925354/

ХабрСистемное мышление: когда разработчик становится архитектором🧩TL;DR Разработчик решает задачи, архитектор - строит будущее.Если ты ещё думаешь, что архитектура начинается с UML-диаграмм - ты опоздал. Она начинается в момент, когда каждый if, костыль и...

“The goal from starting out is to be able to create an API documentation suite from scratch. The minimal viable document, or the minimum the document must contain before it’s released, includes having all the calls covered, a description, even if only one sentence at this point, for every field and call, section overviews, call examples, and examples of each field. I suggest also creating a Postman collection file for each API suite. A Postman collection file is a complete set of all the requests and that each request may be run by clicking it; it’s a convenience to clients.

Being able to create that document indicates the writer’s proficiency in the mechanics of API documentation. There is a sense of accomplishment when achieving this and comfort with this process. And rightly so. They have the privilege now of calling themselves API documentation writers.”

robertdelwood.medium.com/start

Medium · Starting API Documentation Writers: Obstacles To Watch Out ForBy Robert Delwood

"Without clear signposting, an agent might miss your API entirely. If it does discover it, large language models (LLMs) may stumble with undocumented behaviors, hallucinate methods or flood your servers with random calls.

So, it’s important to get it right. Thankfully, strategies are emerging to position APIs for AI agents, from new standards to underground tricks. And, it’s more than just “get an MCP server” (though that’s a crucial step).

The jury’s out on what strategy will be most effective. So I’ve structured this guide to start with broadly agreed-upon best practices, then explore ones still taking shape. Most tips apply equally to public, partner and private APIs."

thenewstack.io/how-to-prepare-

The New Stack · How To Prepare Your API for AI AgentsExperts share how to prepare your API for agentic consumption. Spoiler: It takes more than just wrapping it in MCP.
Continued thread

CouchDB also seems to be a technically simple solution—although it seems more difficult to use. And it's built with erlang!

1. Automatically generating OpenAPI documentation for your web resources doesn't seem doable, but there's perhaps CouchDB's own form of API documentation.
2. HTTP OPTIONS requests are accepted although poorly documented from what I could find.

It'd be nice if CouchDB supported learning about it's API through OpenAPI documentation.

#CouchDB#HTTP#REST