Creating an API style guide

1

StopLight

I was recently asked for my favorite resources and best practices for writing clear and structured API docs. I've developed my own style for writing API docs, but up until now I haven't published it. Although I've mainly worked with REST APIs, this guidance applies equally to GraphQL and any other APIs. But before I get to writing style, the most important requirement for good API docs is a good API. If you're using REST, validate it with Stoplight. If endpoints are inconsistent in how they handle common parameters, there's no way to write around the problem. This seems to be more of an issue with REST and may account for the move away from REST toward GraphQL. The next thing that you need is static, searchable docs. Don't expect your GraphQL users to find the information they need by browsing your schema in Apollo. Don't expect your REST users to scroll to the bottom of the Swagger UI page to find out how to format data for a given endpoint. If you need a no-budget solution, Redocly CLI and Magidoc are good places to start for REST and GraphQL respectively. Unless you use AWS hosting (which doesn't play nicely with Magidoc's clean URLs). And don't think that you're done when you've published your schema. Developers need workflows, code examples and reference information to understand how they are expected to use your API. Ideally, this information should live in a public developer portal. Your rivals are not going to be able to clone your product by examining your API. And even if they start adding features based on it, you'll always be several steps ahead.

#API Tools #APIs #API 30 social mentions

2

Magidoc

I was recently asked for my favorite resources and best practices for writing clear and structured API docs. I've developed my own style for writing API docs, but up until now I haven't published it. Although I've mainly worked with REST APIs, this guidance applies equally to GraphQL and any other APIs. But before I get to writing style, the most important requirement for good API docs is a good API. If you're using REST, validate it with Stoplight. If endpoints are inconsistent in how they handle common parameters, there's no way to write around the problem. This seems to be more of an issue with REST and may account for the move away from REST toward GraphQL. The next thing that you need is static, searchable docs. Don't expect your GraphQL users to find the information they need by browsing your schema in Apollo. Don't expect your REST users to scroll to the bottom of the Swagger UI page to find out how to format data for a given endpoint. If you need a no-budget solution, Redocly CLI and Magidoc are good places to start for REST and GraphQL respectively. Unless you use AWS hosting (which doesn't play nicely with Magidoc's clean URLs). And don't think that you're done when you've published your schema. Developers need workflows, code examples and reference information to understand how they are expected to use your API. Ideally, this information should live in a public developer portal. Your rivals are not going to be able to clone your product by examining your API. And even if they start adding features based on it, you'll always be several steps ahead.

6 social mentions