#apidesign — Public Fediverse posts

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

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

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

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

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

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

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

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

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

Mastering FastAPI Request Bodies: Handling User Profiles and Token Authentication

In 2026, building scalable backend services requires a robust understanding of how API endpoints process complex payloads. This session explores the standard patterns for managing data models and secu...

📺 Watch here: https://www.youtube.com/watch?v=ABt48n3S7UA

##FastAPI ##Python ##BackendDevelopment ##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

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

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

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

"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

"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

"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

"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

Modern Banking Microservices with Clean Architecture, DDD, TDD, .NET 9, and Angular (Monorepo): A Complete Engineering Guide to Building Production-Grade Banking Systems Using Microservices, Docker, CI/CD, Testing, and Angular Nx Monorepos https://leanpub.com/fullstack-banking-microservices by Gustavo Felix is the featured book on the Leanpub homepage! https://leanpub.com #CSharp #ApiDesign #Devops #Angular #MessageDriven #Rabbitmq #Microservices #Git

Find it on Leanpub!

Lately, I have been studying the #SCIM 2.0 standard for representing users and user groups. I was pleasantly surprised that the standard also includes a full #querylanguage that can you can apply to any #API. #apidesign

https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.2

What is the Engineering Design Process? A Complete Guide https://b.mamund.com/3QEIWxA

"The engineering design process is a series of steps that engineers follow to find a solution to a problem."

#api360 #apiDesign #engineeringDesign

"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

Infinite scroll usually fails for boring reasons.

Offset pagination looks fine in the first demo. Then users scroll deeper, queries get slower, and the database starts doing more work for every request.

This article walks through building cursor pagination with Quarkus and PostgreSQL. Not as a pattern diagram, but as a real API that stays fast no matter how far you scroll.

https://www.the-main-thread.com/p/quarkus-cursor-pagination-infinite-scroll

#Java #Quarkus #PostgreSQL #BackendEngineering #APIDesign #Performance

API keys fail quietly.

Most systems still treat them as binary switches:
valid key → full access.

That works right up until a partner link, free tier, or internal tool suddenly unlocks paid or admin features.

This article walks through a Quarkus design where API keys act as identities with feature-level permissions, not just shared secrets.

https://www.the-main-thread.com/p/quarkus-api-key-feature-level-access-control

#Java #Quarkus #APIDesign #SoftwareArchitecture

System Design and Architecture Mastery: Enterprise Integration Platform and NFRs https://leanpub.com/b/systemdesignandarchitecturemasteryintegrationandnfrs by Sameer Paradkar is the featured bundle of ebooks 📚 on the Leanpub homepage! https://leanpub.com #SoftwareArchitecture #DistributedSystems #SystemIntegration #SoftwareEngineering #ApiDesign

Find it on Leanpub!

"even with all that #GraphQL has to offer, #APIdesign remains difficult.

Over time, we’ve developed some proven design philosophies and patterns for easier schema migrations, exposing errors, and avoiding ambiguous or misleading type names."

https://the-guild.dev/graphql/hive/blog/schema-design-best-practices-part-1

Legacy modernization fails at implicit boundaries, not scale. Learn how API contracts, validation, and error handling prevent silent production failures. https://hackernoon.com/legacy-modernization-doesnt-fail-at-scale-it-fails-at-boundaries #apidesign

#SpecDrivenDevelopment flips traditional architecture by making specs executable & authoritative.

Declared intent - validated code via AI-assisted generation, delivering real architectural determinism.

Continuous enforcement kills drift - but demands stronger schema design & contract-first discipline.

#InfoQ ⇨ https://bit.ly/3YCprvu

#SoftwareArchitecture #APIs #APIDesign #AI #GenAI #CodeGeneration

Retries are not harmless.

Without idempotency, they silently corrupt data: duplicate orders, double charges, broken workflows.

I wrote a deep, hands-on guide explaining idempotency keys, the IETF standard, and how to implement them correctly in Java with Quarkus — including concurrency, in-flight requests, TTL cleanup, and real failure scenarios.

https://www.the-main-thread.com/p/java-idempotency-keys-ietf-quarkus

#Java #Quarkus #DistributedSystems #APIDesign #HTTP #IETF #SoftwareArchitecture

"APIs to Capabilities

Enterprises have invested 10-15+ years into exposing enterprise capabilities (internal and external) with APIs. That is not going away. MCP, as exciting as it is, is really just a simple protocol shim for AI models to call tools. But to expose the tools correctly to the model, we need to describe capabilities not just API contract structure:

- tool names should be unique, action oriented (e.g., “listAllTodoTasks” vs just “list”)
- include detailed purpose explanations
- give examples of when to call with example requests/responses
preconditions for using the tool

Using OpenAPI Spec

The OpenAPI Specification contains a number of fields and structures to support adding rich semantic meaning to our APIs:

-Using the info section
- A number of sections offer the ability to link out to externalDocs
- Most sections provide a title, summary, and description field
- You can link out to industry accepted (or enterprise specific) data fields using JSON-LD for very deep semantic meaning
- If none of these are adequate, you can extend the spec with “x-properties”

Let’s take a quick look at an example."

https://blog.christianposta.com/semantics-matter-exposing-openapi-as-mcp-tools/

#APIs #APIDesign #APIDevelopment #OpenAPI #MCP #LLMs #Metadata #AI #GenerativeAI #AIAgents

I’m so excited that this book is back on track!

Build APIs You Wont Hate 2: This Time Its Serious

Roughly 80% of the internet is roughly built APIs, held together with enough duct-tape to choke all the hamsters powering it. Let's learn how to build them properly.

#apidesign
#apidevelopment

https://leanpub.com/build-apis-you-wont-hate-2

Everything I know about good API design

https://www.seangoedecke.com/good-api-design/

#HackerNews #APIDesign #API #BestPractices #SoftwareDevelopment #TechInsights #DeveloperTips

"In our piece exploring whether the AI revolution is leaving APIs behind, we wrote about some of the factors limiting the extent to which AI tools like chatbots can interface with APIs.

Some of these include:

- Limited or no access to APIs for developers
- APIs are sometimes overcomplicated, bloated, or difficult to call
- Legacy APIs (WS/RPC) lack thorough or up-to-date documentation
- APIs sometimes only cover a fraction of the functions available via the UI

It’s worth noting that many of these points impact human API consumers just as much as they do agentic ones. If you’ve ever been in the position of trying to use an API and it falling short of your expectations, you’ll know just how frustrating it can be.

While it’s possible that some of those users will get in touch to ask you to add certain endpoints or clarify things, plenty more won’t. Some developers are more likely to take the view that it’s easier to ask for forgiveness later than permission now, and find some other way to extract the data they’re looking for. In many cases, web scraping offers just such a solution.

Web scraping APIs are a natural evolution of manual scraping techniques, such as using Python to scrape websites. Used for everything from scraping search engine results, like SERP APIs, to product prices and sentiment analysis, there are various services out there that make web scraping very straightforward. And they’re big business."

https://nordicapis.com/are-web-scraping-tools-overtaking-official-apis/

#APIs #WebScraping #SoftwareDevelopment #Programming #APIDocumentation #APIDesign #Python

"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

#API #APIs #APIDesign #REST #APIDocumentation #OpenAPI #DocsAsCode #TechnicalWriting #TechnicalCommunication

"Getting to this point isn’t unusual. Clients clearly think they’re making the call correctly, or else they would fix the endpoint themselves. Some misspellings are difficult to catch. The enum USER_RETREIVE may not be noticed from USER_RETRIEVE, especially if picking it from a list. Misspellings happen and they’re not always caught before making it to the contract. As an aside, that’s why it’s important writers routinely check development’s changes. This applies, too, to our testing calls in Postman, where manually entering endpoints and values are more pervasive.

The reason this isn’t caught is simple: We’re not expecting it.

For our testing, the call is made and we get results. We may even spot check some of them. But generally, results aren’t examined that closely. For instance, how often do you so carefully examine a returned list of 50 or 100 items? You check may check that the objects are complete but not that the list conforms to the search criteria.

The reason this happens is because of an intentional behavior on the server. This behavior is called Lenient Handling or Strict Handling."

https://robertdelwood.medium.com/understanding-query-parameter-handling-in-rest-calls-1821e0c3fa8c

#APIs #RESTAPIs #Rest #APITesting #APIDesign #APIDocumentation #SoftwareDevelopment

#APIs #APIAsAProduct #APIManagement #SoftwareDevelopment #APITesting #APIDesign #APIDocumentation: "I often make the point about API users that they fall into one of two buckets: the conceptual user (the dreamer) and the procedural user (the implementer). Breaking those two down is a blog post for another day, but essentially, this book is aimed at both, leaning more heavily toward the former.

Bruno embarked on his book-writing journey armed with a hefty dose of product thinking. He took the scenic route chatting it up with API aficionados, getting the lowdown of their challenges and triumphs. Turns out, we Product Managers are drowning daily in a sea of technical jargon without a life raft in sight.

If you’re anything like me back in the day, when I was a fresh-faced newbie diving headfirst into the API industry, you’ll relate. I’m talking fingers dancing across the keyboard like they were in some kind of turbocharged typing marathon during every single sit-down with architects, developers, and engineers. Seriously, the clickety clack of the keystrokes echoed as my own personal symphony: Reverie of Desperate Recall.

This book was born specifically for those navigating the waters of building an API product, whether they be product managers, architects, development managers, you name it. So it is for those readers that I would recommend reading this book." https://theapinerd.com/an-api-product-managers-honest-take-on-bruno-pedro-s-book-building-an-api-product-f01038ad2bc3

#WebAPIs #APIs #TypeSpec #APIDesign #APIDocumentation #OpenAPI #DX #DeveloperExperience: "As we navigate the ever-evolving landscape of API design, it’s crucial that we don’t lose sight of the bigger picture. Although tools like TypeSpec offer enticing promises of simplified development and improved developer experience, we must approach them with a critical eye. The allure of code-like constructs should not come at the cost of collaborative, human-centered design principles. OpenAPI, for all its complexities, has made significant strides in democratizing API design and fostering cross-functional collaboration. Let’s not sacrifice all that on the altar of curly braces." https://passo.uno/typespec-openapi-api-design/

#OpenWeb #WebAPIs #APIDesign #W3C #WebDevelopment:"This document contains a set of design principles to be used when designing web platform technologies. These principles have been collected during the Technical Architecture Group’s discussions in reviewing developing specifications, and build upon the Ethical Web Principles [ETHICAL-WEB]. We encourage specification designers to read this document and use it as a resource when making design decisions."

https://www.w3.org/TR/design-principles/