2 posts tagged with "API Documentation"

I use Markdown for note taking, and for personal documentation, most of my SOP/MOP are Markdown based with scripts embeded, I am sure you use it as well, at least in your Git issues, but when it comes to API design with Markdown doesn't seem to be the best choice.

Markdown or YAML/JSON - what's the right tool for your API design?

API development has come a long way, and with it, so has the demand for tools that make it easier to design, document, and maintain APIs. Two notable names that developers often encounter are API Blueprint and Swagger (also known as OpenAPI). These tools, while different in their approach, both aim to improve the quality and clarity of APIs.

When developers integrate systems and a new API version gets released, there's often a common struggle: figuring out what breaks. The task of identifying backward compatibility issues can be tedious and overwhelming. Sometimes, changes in the API are buried deep within documentation - hidden away in a PowerPoint presented to a select group, a demo recorded months ago, or a lengthy PDF you never got around to reading.

The real pain? Even after you track down all this information, a small, overlooked change could cause massive problems in your integration. It's frustrating, time-consuming, and distracting from what developers truly love to do; write code.