Oh Man, Look at Your API!

1

swagger.io

We all know that the most common advice says to document your API but lots of people avoid doing it anyway. While I understand that nobody ever seems to have enough time for these things, it is the face of your API. It might be worth it to put off your much more interesting API coding challenge to invest in writing this documentation. Here are some basic tips for doing it well: You should offer always working examples of HTTP requests and responses or of actual working code. Documentation should be formatted as consistently as the API itself. The foundational principles of your API should be described clearly and in detail. Use API frameworks such as Swagger, Apiary, or Postman.

#API Tools #APIs #Documentation 81 social mentions

2

JsonAPI

Do not even think about constructing new data formats! I've seen APIs with custom data formats and they always suck. Parsing your unique data format slows work down a lot and makes it a chore to do. Sure, I know it is hard to suppress your creativity when it spills out into these strange ideas, and that these are difficult to throw purely because of your own parental feeling towards your creation, but you must resist. We already have JSON, XML, and all the rest, right? They are enough. You should take advantage of specifications like JSON API. Stripe, Braintree, and lots of other companies are already using it successfully. JSON looks good, has an easy-to-use structured data format, and the JSON API spec is generally well thought out. Also, please do not support multiple data formats. Customers do not generally care which standard data format they use because all programming languages and technologies already support data formatting and parsing for every standard type. Including multiple formats only slows your API and documentation maintenance down.

#Development #Online Services #API Tools 44 social mentions

3

Apiary

We all know that the most common advice says to document your API but lots of people avoid doing it anyway. While I understand that nobody ever seems to have enough time for these things, it is the face of your API. It might be worth it to put off your much more interesting API coding challenge to invest in writing this documentation. Here are some basic tips for doing it well: You should offer always working examples of HTTP requests and responses or of actual working code. Documentation should be formatted as consistently as the API itself. The foundational principles of your API should be described clearly and in detail. Use API frameworks such as Swagger, Apiary, or Postman.

#API Tools #APIs #API Management 7 social mentions