Looking for examples of API documentation online? Wondering how the big boys write their API documentation so you can get a little inspiration? Me too.
//Get the REST API Documentation Tutorial here
We’ve being writing a lot of API documents recently for a new client. She asked for examples of how other IT companies publish their API documents online.
- How do they structure their API content?
- What tools do they use to publish their API documents?
- What API documents look just amazing? (I asked that, btw)
[Learn more about this template here]
Examples of API Documentation Online
In no order of preference, here’s some that caught our eye. If we missed one, let us know here.
The Sun Cloud API
This wiki specifies a RESTful API for creating and managing cloud resources, including compute, storage, and networking components.
This technical document library puts the API in context for readers:
The API tech writers tell us:
“Usage of the API is via the HTTP protocol. The GET, POST, PUT, and DELETE requests are all used, although most tasks can be accomplished with GET and POST. Resource representations are in JSON.
The API presupposes no particular structure in the URI space. The starting point is a URI, supplied by the cloud service provider, which identifies the cloud itself. The cloud’s representation contains URIs for the other resources in the cloud, and also for operations which may be performed upon them (for example deploying and starting virtual machines).”
It then goes into the specifics of what’s included in the specification.
The specification of the Sun Cloud API includes:
- Common behaviors that apply across all requests and responses.
- Resource models, which describe the JSON data structures used in requests and responses.
- The requests that may be sent to cloud resources, and the responses expected.
Huddle APIs
Many tech writers and developers favorite API documents online. There’s a lot to admire about the way Huddle explain their APIs.
Huddle provide access to their services via a set of RESTful HTTP services. This project is a public repository for documentation and examples.
Zoho Subscriptions API
I’d forgotten about Zoho. They have a remarkable range of very slick and impressive web-based tools.
So, what do they say?
“The Zoho Subscriptions API allows you to perform all the operations that you do with our web client.
Zoho Subscriptions API is built using REST principles which ensures predictable URLs that make writing applications easy. This API follows HTTP rules, so a wide range of HTTP clients can be used to interact with the API.”
It’s written in a nice, confident tone of voice and explains how the API is designed in a helpful way.
Whoever wrote this, knows their onions, as they say down our way.
“Every resource is exposed as a URL. The URL of each resource can be obtained by accessing the API Root Endpoint.”
Twitter API
If you’re a tech writer looking for a template for online API documents, it’s hard to beat Twitter’s API pages.
Not only does it give a staggering amount of useful examples, code samples, and guidelines, it goes one further and shows you the current performance and availability status.
Here are some resources that will help you understand the basics of all our APIs. If you haven’t already, make sure that you have familiarized yourself with the Developer Rules of the Road. Check out the OAuth section to learn more about how we do authentication and authorization.
REST APIs
Notice how the writing style is confident without being brash or bragging. Again, kudos to the writers. Nice one!
“The REST APIs provide programmatic access to read and write Twitter data. Author a new Tweet, read author profile and follower data, and more. The REST API identifies Twitter applications and users using OAuth; responses are available in JSON.”
If your intention is to monitor or process Tweets in real-time, consider using the Streaming API instead. If you’re looking for a benchmark for your APIs, Twitter may be hard to beat.
//Get the REST API Documentation Tutorial here
Readability APIs
Very simple, very elegant.
The Readability APIs are available in three distinct flavors:
- READER API – allows you to build reading and queueing functionality right into your app.
- PARSER API – provides access to Readability’s best-of-breed web content parsing engine.
- SHORTENER API – allows you to access Readability’s unique URL shortener.
To get started, you’ll need to request a set of API keys. Grab Your Keys.
Parse
The REST API lets you interact with Parse from anything that can send an HTTP request. There are many things you can do with the REST API. For example:
- A mobile website can access Parse data from JavaScript.
- A webserver can show data from Parse on a website.
- You can upload large amounts of data that will later be consumed in a mobile app.
- You can download recent data to run your own custom analytics.
- Applications written in any programming language can interact with data on Parse.
- You can export all of your data if you no longer want to use Parse.
Twilio REST Web Service
The Twilio REST API allows you to query meta-data about your account, phone numbers, calls, text messages, and recordings. You can also do some fancy things like initiate outbound calls and send text messages.
Since the API is based on REST principles, it’s very easy to write and test applications. You can use your browser to access URLs, and you can use pretty much any HTTP client in any programming language to interact with the API.
The Twilio REST API is served over HTTPS. To ensure data privacy, unencrypted HTTP is not supported.
Phone.com
Possibly my personal favorite.
Whether you’re using a REST request to change a simple setting in your Phone.com account or to control a complex phone call, our API services use the HTTP protocol for all communications. The Phone.com API is a REST API. This topic covers how to structure Phone.com API requests and responses, and provides examples that you can review when writing your own API requests.
Getting Started Guide
- API Features
- Systems & Requirements
- Configuration Checklist
API Reference
- API Reference Guide
- Requests & Responses
- Error Reference Guide
API in Action
- Tips & Best Practices
- API Tutorials
- Idea Inspiration
Github
Many API methods take optional parameters. For GET requests, any parameters not specified as a segment in the path can be passed as an HTTP query string parameter:
jQuery
Did we almost forget jQuery?
jQuery is a fast, small, and feature-rich JavaScript library. It makes things like HTML document traversal and manipulation, event handling, animation, and Ajax much simpler with an easy-to-use API that works across a multitude of browsers. If you’re new to jQuery, we recommend that you check out the jQuery Learning Center.
Google Drive API
This API reference is organized by resource type. Each resource type has one or more data representations and one or more methods.
//Get the REST API Documentation Tutorial here