• noat Blog - Quality API Documentation Examples

Quality API Documentation Examples

Here at noat we are passionate about creating great documentation and believe it to be the most important aspect of user design. You might have the best system in the world, but without sufficient documentation people will fail to utilise it effectively. Finding documentation that is well-written, comprehensive and up-to-date can be a challenge and we have often found it has become a casualty of the development process.

In our first blog post we are aiming to highlight some of the best examples of Reference API Documentation that we have used in the past.

What is an API?

An API is a set of standards for accessing an internet based software program or internet-based tool. Software companies can choose to release an API to the general public so that other software developers can utilise and integrate their services into their own development. For example Twitter has released its own API which developers can use to integrate Twitter services into their own website or custom app.

Optimal API reference documentation should aim to list all functionality in detail with examples given in multiple programming languages and be displayed in a readable manner.

In no particular order, the following are Noat's top examples of API documentation we have used:

1. Stripe - http://stripe.com/docs/api

What is Stripe?

Stripe offers a suite of products that that allow websites to accept a variety of payment on their website to customers. Web developers can use the Stripe API on their website to easily facilitate a variety of payment options instead of having to set up a different merchant account.

Why is the documentation good?

The API documentation is highly detailed, includes example code in a wide range of programming languages (Ruby, Python, PHP, CURL & Node) and has a clean interface. Stripe documentation also includes useful tutorials to get started with their service.

 2. Librato - http://dev.librato.com

What Librato?

Librato services provide a comprehensive solution for monitoring and understanding the metrics that impact a clients business. Librato integrates and provides statistics for a huge variety of platforms including Amazon Cloudwatch, Heroku and Collectd.

Why is the documentation good?

Like the Stripe documentation above, the API is comprehensive and is easy to read and understand. They also have an active knowledge base to help you get the best out of their services.

3. Brighter Planet CM1 - http://impact.brighterplanet.com/documentation

What is Brighter Planet CM1?

Brighter Planet CM1 provides carbon and energy impact assessments in the cloud. For example is can provide greenhouse gas modelling for cars operated over time to carbon analysis for parcel transport by shipping.

Why is the documentation good?

The API documentation for CM1 is concise and to the point. The documentation includes examples with diagram along with bespoke query builders for each service they provide, which allow you to get to grips with their API quickly.

4. Gevent - http://www.gevent.org/reference.html

What is Gevent?

Gevent is a coroutine-based Python networking library.

Why is the documentation good?

The documentation is well organised, elegant and comprehensive with detailed examples of each instance.

5. Leaflet - http://leafletjs.com/reference.html

What is Leaflet?

Leaflet is a open-source JavaScript library for mobile interactive maps using HTML5 and CSS3. Its users include the Wall Street Journal, Pinterest and Wikimedia.

Why is the documentation good?

Leaflet's API documentation is a particular team favourite - we find it sophisticated, well written and stylish with each function explained in detail. Leaflet also features comprehensive tutorials including a quick start guide and how to tune it to mobile platforms.

 

The above 5 examples are just a few of the many quality API documents noat has used over the years and are a perfect starting point to look to when writing your own API documentation. We regularly post on Twitter and LinkedIn, make sure to follow us for more great examples.

12 Stukeley Street
London
WC2B 5LQ

phone: +44 (0)20 33 22 55 10
fax:       +44 (0)20 33 22 55 01

email: info@noat.com

Privacy Policy
Anti-Spam Policy