#apidesign — Public Fediverse posts

The client makes a synchronous call, and the API replies right away with HTTP 202 Accepted plus a Location header pointing to a status endpoint to poll.

#Fintech #APIDesign

via @dotnet : Announcing v2.0 of the official MCP C# SDK

https://ift.tt/9JGw6W2
#MCP #CSharpSDK #MCPv2 #StatelessByDefault #MRTR #MultiRoundTripRequests #ASPNetCore #HTTPTransport #WebAPI #ApiDesign #HttpHeaders #McpHeader #McpParam #HeaderRouting #LoadBalancing…

"That means that your API UX must be excellent, and the integration with the application must be flawless. It’s only at that point that you start seeing some signs of revenue. How, then, can you boost your returns without all this effort?

AX is the answer. It’s the new DX and API UX all in one. On steroids! In short, making AI agents your primary API consumers is now your goal. Let me repeat. AI agents are now your main API consumers. Everything else is just noise. And, to get there, you need to provide an excellent AX. The amount of API requests AI agents make is directly related to the number of prompts their users submit. On top of that, onboarding is practically taken care of with solutions like the OAuth 2.0 Dynamic Client Registration, or the more granular x402 Agentic Authorization Flow. Billing moves from a SaaS-oriented subscription model to a metered reality, where agents are the ones making the purchase decisions. In this new state of play, if agents have success completing tasks using your API, they’ll likely return. If your AX is poor, agents will churn and find a more efficient API to save tokens.

Offering a good AX starts with having all your documentation in a way a machine would understand."

https://apichangelog.substack.com/p/why-ax-is-the-new-standard-for-api-success

#APIs #AI #AIAgents #AgenticAI #AX #AgenticExperience #APIDocumentation #DX #DeveloperExperience #APIDesign

Here’s why contextual and use case-based documentation matters a lot when it comes to APIs:

“The problem is that documentation is often organized entirely around individual endpoints with very little cross-endpoint guidance, implicit prerequisites, or multi-step call documentation. For this reason, API use often involves tribal knowledge held by the average human operator.

A better way to organize this, or perhaps a complementary way, is to create documentation around workflows and common scenarios. You don't have to document every single potential interaction. In many cases, simply documenting common use cases and then delineating what they share is more than enough for the agentic systems to infer how the API actually functions in practice. This, alongside additional deterministic context, will help agents understand your systems in a human-like context without having to have a human on the other side of the request.

The goal: Provide documentation not just of individual endpoints but of the collective flow between them, allowing agents to understand your service properly.”

https://nordicapis.com/10-factors-for-checking-your-apis-ai-readiness/

#API #APIs #APIDocumentation #AI #AIAgents #TechnicalWriting #SoftwareDocumentation #APIDesign

"Overall, you’re introducing a new layer of information that you’ll have to keep in sync with any future API changes.

Feeling unresolved? That’s because the decision to adopt this taxonomy depends on your primary consumer. As far as I see it, you have two options. If your API is purely for traditional developer-built integrations or direct human consumption, the effort to add a taxonomy might be higher than its benefit. However, if you’re targeting AI agents, a taxonomy is something you need to have. Without it, machine consumers won’t be able to make the most of your API in a cost-effective way. And they’ll probably look elsewhere, which is something you want to avoid, right? Well, I’ve made my point. The decision is in your hands now."

https://apichangelog.substack.com/p/the-taxonomy-of-api-operations

#AI #GenerativeAI #AIAgents #APIs #API #APIDesign #SoftwareDevelopment #Programming #APITaxonomy

A lot of teams say they “handle errors” when what they really mean is that exceptions eventually turn into JSON.

This piece pulls together the Quarkus reading path for RFC 9457, HTTP response design, OpenAPI, versioning, and deprecation so the unhappy path becomes part of the contract instead of an afterthought.

https://www.the-main-thread.com/p/quarkus-api-errors-rfc9457

#Quarkus #APIDesign #OpenAPI

rate limiting is one of those things every API needs but half implement wrong. fixed window leaks at the boundary. sliding window is better. token bucket handles bursts best. return 429 with Retry-After — that one header saves your consumers so much pain. #apidesign #developer #programming

Ever shipped an API and regretted your generic signatures later? Wildcards everywhere. Confusing bounds. Mental overhead. Michel Charpentier breaks down why variance matters—and why #Java still feels heavy here.

Read + apply: https://javapro.io/2026/01/27/what-i-still-miss-my-most-wanted-java-features/

#APIDesign #Generics #JVM

Most devs think backend = APIs.
It’s not.
It’s:
• Efficient request handling
• Clean architecture
• Smart DB design
• Caching strategies
• Security
• Reliability under load
Great backend ≠ just code
It’s systems that don’t break in the real world.
Tools change. Principles don’t.

https://jaswalaryan.space/article/backend-development-beyond-apis-complete-guide

#BackendDevelopment #WebDevelopment #APIDesign #SoftwareEngineering #SystemArchitecture #DatabaseDesign #Caching #Security #PerformanceOptimization #DevOps #Scalability #CodeQuality #Programming

If this resonates, share your service template patterns or open an issue with gaps you hit in production.
If gogen helps, a star and field feedback help prioritize what to improve next.
#OpenSource #GoLang #BackendEngineering #Observability #APIDesign #CloudNative #DistributedSystems

Currently integrating with an API that uses pagination.

To get the next page of results you just provide a page=x parameter.

The number of pages info is in the results, so you can use that to build the pagination engine.

What happens if you go over the number of pages available? You get the last page of results again, with a 200 response code.

Fair play I guess. A simple trap to catch the idiot developer who can't count :D

#api #apiDesign

🎥 𝗩𝗶𝗱𝗲𝗼 𝗜𝗻𝘁𝗲𝗿𝘃𝗶𝗲𝘄 𝘄𝗶𝘁𝗵 𝗘𝗿𝗶𝗸 𝗪𝗶𝗹𝗱𝗲 & 𝗧𝗵𝗶𝗹𝗼 𝗙𝗿𝗼𝘁𝘀𝗰𝗵𝗲𝗿 𝗼𝗻 𝘁𝗵𝗲 𝗖𝗣𝗦𝗔-𝗔𝗱𝘃𝗮𝗻𝗰𝗲𝗱 𝗟𝗲𝘃𝗲𝗹 𝗠𝗼𝗱𝘂𝗹𝗲 𝗔𝗣𝗜 – 𝗥𝗲𝗮𝗹 𝗜𝗻𝘀𝗶𝗴𝗵𝘁𝘀 𝗶𝗻𝘁𝗼 𝗠𝗼𝗱𝗲𝗿𝗻 𝗔𝗣𝗜 𝗔𝗿𝗰𝗵𝗶𝘁𝗲𝗰𝘁𝘂𝗿𝗲 ✨

#APIs drive scalable systems, business value, and AI-ready architectures. Erik Wilde and Thilo Frotscher, two of the module’s curators, share insights on design, governance, DX & AX, and building APIs that truly work.

Watch the full interview 👉 https://t1p.de/td3mh

#iSAQB #Softwarearchitecture #CPSA #AI #API #APIDesign

Build GenAI Agents with OpenAI + vLLM: Develop portable AI agents in Python with structured outputs, tool calling, OpenAI Agents SDK, vLLM, model switching, CLI, API, and Docker deployment by GitforGits | Asian Publishing House is the featured book on Leanpub!

Link: https://leanpub.com/aiagentwithopenaivllm

#Ai #ApiDesign #Docker #Python #SystemIntegration

I always struggle to determine if my API server should return *400 Bad Request* or *422 Unprocessable Content* for bad input. Meanwhile, SonarCloud returns *404 Not Found* if I'm not authenticated.
#SoftwareDevelopment #ApiDesign

"Consumers want to be able to try an API operation and access concrete example information, or configuration data, such as credentials. Markdown alone isn’t going to provide these elements for you. Fortunately, there’s something else that will, as we’ll see next.

The solution you need is called MDX. It’s a superset of Markdown that lets you embed components within your content. Or just render dynamic information obtained from executing JavaScript. You get to keep the simplicity and versatility of Markdown. But now, you can also use dynamic elements and data. This completely changes the game for API documentation. You can, for instance, embed a component to show the consumer’s API key, or one to make an API request and show its response. This hands-on interactivity helps users test the API faster. And, because of that, it significantly reduces the Time to First Call, or TTFC. Since a low TTFC means the API onboarding experience is excellent, it translates directly into a higher perception of quality. Which is exactly what you’re looking for.

Moving from pure Markdown to MDX doesn’t have to be complicated. However, and especially if you have little coding experience, putting an MDX system together from scratch can be challenging. Luckily, there are many systems that already support MDX. Docusaurus, for instance, supports it by default. Astro is another example of a content system where you can use MDX. There are more options, including commercial ones. What I’d recommend, though, is to check out the official documentation and have a go at the MDX playground."

https://apichangelog.substack.com/p/making-api-documentation-dynamic

#API #APIDocumentation #TechnicalWriting #Markdown #MDX #APIDesign #DX #DeveloperExperience

"In a previous post on agent experience (AX), we wrote that “Artificial intelligence tools are bad at inferring context or reading between the lines,” and that “content designed for consumption by AI should look less like a blog post and more like a legal contract. Great agent experience is all about being as clear and predictable as possible.”

Where possible, we need to eliminate assumptions that only make sense to human readers. LLMs aren’t as forgiving of undocumented constraints, inconsistencies, or vague descriptions as a human reader might be. If you’re struggling with that, we can lean on AI tools — it makes sense that AI would know what AI likes, right? — for identifying some of these gaps.

When we covered AI assistants for API developers, for example, we identified LintGPT as a useful tool for its ability to automate the creation of an API style guide, enforce specification standards, and even catch breaking changes before deployment.

API specifications are no longer just documentation. They’re living contracts with machines, which increasingly have the power to read and interact with said contracts. Improving clarity, consistency, and precision might create a few initial headaches, but it opens the door to smarter tooling, faster iteration, and APIs taking pride of place in an increasingly AI-driven ecosystem."

https://nordicapis.com/how-llms-are-changing-the-way-we-build-api-specifications/

#AI #GenerativeAI #LLMs #APIs #APIDesign #APISpecifications

Build GenAI Agents with OpenAI + vLLM: Develop portable AI agents in Python with structured outputs, tool calling, OpenAI Agents SDK, vLLM, model switching, CLI, API, and Docker deployment House is a new release on Leanpub!

Link: https://leanpub.com/aiagentwithopenaivllm

#ai #ApiDesign #Docker #Python #SystemIntegration

Validation logic drifting between frontend, backend, and batch jobs is a real production problem.

This article shows how to move validation into your Protobuf schema using Protovalidate, and enforce the same rules in Quarkus, JavaScript, Python, and more.

Schema as contract. Validation as infrastructure.

👉 https://www.the-main-thread.com/p/protobuf-protovalidate-quarkus-schema-validation

#Java #Quarkus #Protobuf #APIDesign #SchemaFirst #BackendEngineering #FOSS

🧩 𝗔𝗣𝗜𝘀 𝗮𝘀 𝗦𝘁𝗿𝗮𝘁𝗲𝗴𝗶𝗰 𝗕𝘂𝗶𝗹𝗱𝗶𝗻𝗴 𝗕𝗹𝗼𝗰𝗸𝘀 – 𝗡𝗲𝘄 𝗔𝗿𝘁𝗶𝗰𝗹𝗲 𝗯𝘆 𝗘𝗿𝗶𝗸 𝗪𝗶𝗹𝗱𝗲, 𝗧𝗵𝗶𝗹𝗼 𝗙𝗿𝗼𝘁𝘀𝗰𝗵𝗲𝗿 & 𝗙𝗮𝗹𝗸 𝗦𝗶𝗽𝗽𝗮𝗰𝗵 ✨

#APIs are far more than technical interfaces. In their latest article, @sippsack , Erik Wilde, and Thilo Frotscher explain how APIs become strategic building blocks for modular IT landscapes, scalable systems, and sustainable digital business models. 💡

Read the full article on the #iSAQB blog 👉 https://t1p.de/0x4ss

#SoftwareArchitecture #APIDesign #APIGovernance #OpenAPI #AsyncAPI

Ever shipped an API and regretted your generic signatures later? Wildcards everywhere. Confusing bounds. Mental overhead. Michel Charpentier breaks down why variance matters—and why #Java still feels heavy here.

Read + apply: https://javapro.io/2026/01/27/what-i-still-miss-my-most-wanted-java-features/

#APIDesign #Generics #JVM