fosstodon.org is one of the many independent Mastodon servers you can use to participate in the fediverse.
Fosstodon is an invite only Mastodon instance that is open to those who are interested in technology; particularly free & open source software. If you wish to join, contact us for an invite.

Administered by:

Server stats:

8.8K
active users

#apidocumentation

0 posts0 participants0 posts today

“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

"How to leverage documentation effectively in Cursor through prompting, external sources, and internal context

Why documentation matters

Documentation provides current, accurate context. Without it, models use outdated or incomplete training data. Documentation helps models understand things like:

- Current APIs and parameters
- Best practices
- Organization conventions
- Domain terminology

And much more. Read on to learn how to use documentation right in Cursor without having to context switch."

docs.cursor.com/guides/advance

CursorCursor – Working with DocumentationHow to leverage documentation effectively in Cursor through prompting, external sources, and internal context

🚀 New Release: API-Doc-Crafter just got sharper. Cleaner. Meaner.
Giving my little OpenAPI merging monster some upgrades.

It all started with a simple idea: merge OpenAPI specs from multiple repos.
Now? It transforms outdated Swagger specs to OpenAPI 3+, generates HTML pages with full navigation, and allows customization via config or env.

✨ SecurityRequirement deduplication - because why merge APIs if you can't also merge logic?

🧠 Custom metadata enrichment - inject your info, license, contact, and docs straight from config. No more excuses.

🔁 Better parser fallback - now tries more ways to read broken specs than your average intern in panic mode.

🎭 Variable substitution in outputs - ${variables} be gone. Use env or config, stay DRY, stay sane.

🧪 Tests expanded. HTML, JSON, YAML outputs covered like a nuclear bunker.

🧰 Powered by GraalVM, no reflection, blazing fast.
🐳 Native Docker builds.
🧼 Reflection config surgically trimmed. Less bloat. More edge.

Project: github.com/YunaBraska/api-doc-
Happy crafting. And remember: if your docs aren't automated, they're probably lies.

"Let me be blunt.

If your startup offers APIs and you don’t have a portal, you’re lighting developer acquisition money on fire. 💵 🧯🚒

Here’s what a good portal actually does:

Shortens time-to-value: faster POCs, faster adoption.

Reduces support tickets: devs can find what they need.

Builds trust: your API feels stable, documented, and ready.

Increases conversion: when docs show how easy it is to integrate, not just tell.

Still sending PDF onboarding packets to partners?

C’mon, boo. 🥲"

quetzalliwrites.com/newsletter

Quetzalli WritesQuetzalli Writes | Educational Tech Content & Ghostwriting¡Hola, Tech Writing Friends! Your API is powerful. Even your docs are pretty decent. But… where the hell is your developer portal ? If you’re shipping APIs and expecting developers to magically integrate without a centralized place to get credentials, try out endpoints, or even find updated gui

"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."

gist.github.com/briandominick/

GistAPI Documentation Decision MatrixAPI Documentation Decision Matrix. GitHub Gist: instantly share code, notes, and snippets.
#API#APIs#APIDesign

"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."

robertdelwood.medium.com/under

Medium · Understanding Query Parameter Handling in REST CallsBy Robert Delwood
#APIs#RESTAPIs#Rest

“Fortunately, I think there’s a good alternative to the dismal picture of brain-dead tech writers pressing buttons on AI machines and passing the content to SMEs for review. That alternative is to focus on what AI algorithms can’t do (at least not with a few button clicks). In this revised approach, tech writers offload the simple tasks to AI tools to fix while focusing their real time and energy on more complex, ambitious tasks that are beyond the straightforward capabilities of AI tools.

When I say beyond AI capabilities, I still mean AI tools might assist or augment tech writers in the work; it’s just that the tasks aren’t as simple as the mechanical tasks of fixing doc bugs that I described earlier (e.g., “what’s the issue? what’s the fix?”).

For example, when I set about creating complex tree diagrams showing all elements in an API, this was a new kind of documentation that hadn’t been done before at my company. It became an instant hit and one that proved challenging to maintain and grow and fix, but still worthwhile. (In fact, in a chat with a product manager last week, he wondered if our tree diagram page wasn’t the most popular page in our documentation.)

If we focused more on these sophisticated tasks (beyond click-button AI), I think tech writers could have a brighter future.”

idratherbewriting.com/blog/rec

I’d Rather Be Writing Blog and API doc course · Fixing bugs without thinking, Recursive Self-Improvement, and the shift towards more complex tech comm tasksThis post includes a mix of various thoughts on AI, including fixing bugs without thinking, competitive pressures to adopt AI workflows, risks of atrophied critical thinking, recursive self improvement, and the shift toward more complex tech comm tasks. There’s not necessarily an argument throughline here, just various thoughts and perspectives on AI topics in my tech comm world.

“A README acts as the front door to an API, offering consumers brief and sufficient information to get started. A full documentation is a place where consumers go to when they need to find information about any detail of the API. Having one doesn't mean you shouldn't have the other. But, having a README is, in my opinion, the very minimum you can do if you're serious about your API. And, at the very minimum, there are three elements I'd consider.”

#APIs #APIDocumentation #Markdown #TechnicalWriting #Git #DocsAsCode

apichangelog.substack.com/p/th

The API Changelog · Three Elements of a Good API READMEBy Bruno Pedro

"A quick start guide offers concise step-by-step instructions to help users quickly get started with a product, service, or tool. In the context of API documentation, a quick start guide covers the minimal steps required for developers to make their first API call successfully. It typically provides steps such as how to create an account, where to locate API keys or credentials, how to authenticate, example code to make a basic API call, a way to display the response, and troubleshooting tips. The goal is to deliver a quick win to developers and provide a foundation to integrate with your API."

apimatic.io/blog/how-to-design

www.apimatic.ioHow to Design a Quick Start Guide for Your APILearn how Quick Start Guides help developers, what makes a good quick start guide and an example of a quick start

"Normally, you don't visit your own API documentation that often, right? I mean, if you already know how your API works, why would you want to consult its documentation? Conversely, there's a place you visit—or should visit—very often, with information you care about your API. I assume you have an API dashboard where you can review metrics such as the ones I described earlier. Usually, the dashboard lives close to the API gateway, or somewhere where other company-wide observability tools reside. What I'm proposing here, in short, is that the API documentation can be the best place to present those metrics to you, the producer.

Being able to see the metrics you care about right near the documentation for each part of your API feels refreshing. You could, for instance, be looking at the reference of one operation and immediately see its usage trend, the error rate, the number of active consumers in the last hour, and so on. What's more, some of the information visible only to you could also be actionable. You could, for instance, open the pending support requests to see what the top complaints are. Or, you could immediately check why there's such a percentage of errors on one single operation.

While most information would be restricted to you, the producer, I argue that some things could even be openly shared with your API consumers. Imagine being a consumer and seeing a list of "popular" API operations right on the documentation. Or understanding if a certain operation is producing a high error rate. All these things could be easily available in the API documentation."

apichangelog.substack.com/p/pr

The API Changelog · Producer-Oriented API DocumentationBy Bruno Pedro

"Similar to Wood’s conviction that AI’s transformative potential doesn’t come from simple tasks like writing emails, tech writers will likely find conviction when they go beyond fixing simple grammar errors to using AI for developing conceptual articles, generating release notes, or understanding connections across disparate API products.

One of my colleagues compared using AI like learning to play an instrument—it’s one thing to have an intellectual understanding about the instrument and notes, but knowing how to play an instrument well is entirely different. It takes practice, experimentation, learning, diligence, and time. Maybe too many tech writers feel that AI should provide a push-button solution to creating documentation effortlessly (a misguided perception based on too much AI hype). When pushing that button doesn’t magically produce great docs, perhaps they become cynical and dismissive?"

idratherbewriting.com/blog/tre

I’d Rather Be Writing Blog and API doc course · My 2025 trends predictions for tech commIt’s that time of year again when we take to analyzing trends. If you know me, you’re probably gearing up for a load of AI-optimistic predictions because, as I’ve noted in previous posts like Unpacking the issues from AI, I’m an AI optimist. However, my AI optimism isn’t based on hype or the current tech zeitgeist. Rather, I’m an AI optimist because my daily experiences using AI for technical documentation, especially API docs, throughout 2024 has shown it to be invaluable.

"The quality of job descriptions varies wildly. That means how the job is described, the components of the job, and expertise expected for each component. The descriptions are better for the common job types, such as project and product managers, developers, and sales. Companies know what those are and have experience hiring those.

All that falls apart when it comes to writing, of any type, and specifically API documentation writers. CEOs, who I love to vilify for this reason, generally don’t understand technical writing and technical writers. To them, and that attitude often trickles down the table of organization, see copy, marketing, content, and technical writing as the same and interchangeable. I believe this causes the low pay rates, because we’re seen as a commodity, going at market rate. A doctor with 15 years of experience is treated as an expert. A writer with 15 years of experience competes in the marketplace with junior writers. A shame for sure. I digress some but that needed to be pointed out.

There is information to be mined from bad job descriptions, if you know what to look for and know how to use that information."

robertdelwood.medium.com/readi

Medium · Reading API Documentation Writer’s Job DescriptionsBy Robert Delwood

"The only goal of API documentation has to be for “great documentation.” I define that as documentation so clear so it defies misunderstanding. Why would it be anything else? While it sounds like a lofty goal, it’s easily obtainable and within everyone’s reach. It begins by thinking like a developer. API documentation writers have to move away from thinking like a technical writer.

When documenting strings, many writers just think about this as little more as characters within quotes, or as a combined set of characters. The following are two examples commonly documented for strings. In a moment, you’ll see how inadequate these really are."

robertdelwood.medium.com/the-t

Medium · The Truth About Describing Strings - Robert Delwood - MediumBy Robert Delwood

"In short, APIs are how businesses speak to one another. Breaking this oath with a poor integration experience is a surefire way to reduce your business potential. By utilizing a source of truth and baking a specification-first approach into your API development and documentation practices, you more clearly communicate changes, reducing the possibility of broken clients and promoting forward compatibility. Great API products must be well-described, easy to understand, and predictable in the long run.

In the end, the business effects of specification-driven development are manifold. Whether you're building RESTful, GraphQL, or event-driven partner services, having reliable API documentation is important to compete in the digital economy. This consistency equates to a better partner experience, leading to stickier partners and less customer churn. By enabling smoother integrations and reducing frustration, spec-first documentation directly contributes to partner retention and loyalty, which ultimately drives revenue growth."

bump.sh/blog/how-spec-first-ap

bump.shHow Spec-First API Documentation Aids Partner Integration · Bump.shPartner APIs are far more common than public-facing APIs. Yet, inaccessible documentation for these APIs is often a big barrier to partner success. In fact, nearly 40% of developers say inconsistent docs are their biggest roadblock when it comes to API integration, found the 2024 State of the API Report. Pain points around API documentation can cause miscommunications, errors, and time delays.

"So, if developers aren’t going to use Try Its, what harm is there for including them? They can just ignore them, right? Perhaps, but there’s more to it.

It takes up valuable screen real estate (the right corner above the fold). Writers need to optimize the developer experience, even to the point of minimizing eye movements. Make it easy to find details. That space could be used more productively.

We “should know” but we don’t. This segues into the real reason. It demonstrates that writers don’t know the developer experience. Let’s be blunt. We’re delivering documentation suites that have not been tested properly, calls that are unlikely to have been tested, and tools developers don’t use. Not understanding these issues is the fundamental reason writers also need developer experience. Writers simply can’t empathize with own audiences, which means we supplying developers with inadequate and incomplete tools and documentation. This is a real concern.

This is not a condemnation. Quite the opposite. API documentation writers need to empathize with developers. Writers do this by treating this as a craft, learn a little about development each day, and move slowly along the experience spectrum towards the developer’s end. Learn a language. It doesn’t matter which one. Java, JavaScript, to DOS batch commands, UNIX command line programming, Word macros, Python, or even AutoHotKey*. All of these have programming concepts and that’s what matters. Learn about them, which requires using an API guide, craft statements, and debug them is at the heart of the matter."

robertdelwood.medium.com/why-i

Medium · Why I Don’t Like “Try It” - Robert Delwood - MediumBy Robert Delwood

"A handful of root causes are likely behind API drift. One standout point is the simple fact that API documentation is typically incomplete. Only 10% of organizations fully document their APIs, found a 2023 EMA report. Without a strong documentation culture or comprehensive API inventory management, it’s more common to see a disorganized use of service descriptions.

Furthermore, many groups are still early on in their API governance strategies. As the number of APIs increases within a company, those without established standards for maintaining the API lifecycle are more likely to experience incompatibilities or even see services turn into shadow or zombie APIs.

According to Lorna Mitchell, VP of Developer Experience at Redocly, API drift is intrinsically tied to a lack of comprehensive testing. Drift can occur for design-first APIs if there aren’t clear tests of whether what is built actually matches what’s described. This is a problem that can easily become endemic, she says. “Code gets duplicated, and the chasm widens.”"

nordicapis.com/understanding-t

Nordic APIs · Understanding The Root Causes of API Drift | Nordic APIs |Why do so many APIs drift from their specifications? It's due to immature API development practices and a lack of ownership for maintenance.

"I’ve outlined each step of my process to illustrate the iterative nature of working with AI tools, which become like power tools in the hands of skilled writers. Simply asking the AI to generate a final draft of the documentation based only on the original meeting transcript would likely lead to a poor result, prompting the writer to mistakenly conclude that AI tools are unsuitable for documentation tasks like this. But by using an approach that involves multiple processes and iterative drafts, the AI tools produce a more intelligent outcome.

Some might argue that this extensive iterative process — with its numerous drafts, prompts, and reviews — negates the time-saving benefits of using AI tools. Why not just write it yourself from scratch? However, I still think writing the draft from scratch would be more time-consuming and be less accurate. Although it seems like a lot of iterative steps, remember that the AI performs each step in a matter of seconds. Additionally, writing sentences from scratch consumes a lot of mental effort, whereas using AI tools is a more mechanical task with only judgement and editorial acumen needed. For instance, I could likely watch a football game or a TV show while guiding the AI through these steps. In contrast, drafting the content manually would likely exhaust me within two hours."

idratherbewriting.com/ai/promp

I’d Rather Be Writing Blog and API doc course · From engineer interviews to written draft, with chain of thought reasoningIn this prompt engineering series, I’ve often focused on a specific technique one at a time, but in this tutorial, I’ll show how multiple techniques can work together successfully, such as the following:

#APIDesign #APIs #APIGovernance #APIDocumentation #DX #DeveloperExperience: "Most enterprises face a widening API portfolio with an increasing number of API design styles and standards. “Almost all organizations are doing this,” says Brian Otten, VP of digital transformation catalysts at Axway. “I recently talked to a large food retailer that wants to see REST APIs alongside event-based resources and GraphQL,” Otten says.

In addition to the patchwork of API styles, most companies use multiple API gateways or management tools simultaneously. “We are at a point where organizations who already have API management solutions are buying API management solutions,” says Mark O’Neill, VP analyst at Gartner. O’Neill notes that in some cases, this is to replace the current platform, but in many situations, it’s cumulative.

In this multi-paradigm world, API governance is emerging as a key element for bridging disparate styles and avoiding the pains of a sprawling technical portfolio. According to API industry experts, governance will require a greater emphasis on documentation, centralizing common patterns across the organization, consolidating tools, and building internal platforms that improve the developer experience."

infoworld.com/article/3529600/

InfoWorldHow do you govern a sprawling, disparate API portfolio?The API revolution wasn’t televised. Now, enterprises must figure out how to weave together a patchwork of API styles, standards, and gateways.