Getting Started with a REST API

The first to look for when working with a new API is the documentation provided by that API. This will typically tell you what security is required, the methods supported by the API and the expected format of the requests and response. Typically this will provide all the required information for interacting with the API.

Documentation however varies from API to API as does the quality of the documentation. Some providers have detailed documentation with examples whilst others can provide just the minimum amount of information required to interact with it.

APIs can also develop and change over time as more capability is added or requirements change. The documentation should provide a view on the current state, and of any changes. It may also describe different versions of an API.

There is no set format or structure for documenting an API so each is different and will require a degree of investigation. However they will share common elements such as authentication, supported methods and response structures along with any limitations such as number of requests supported in a given time frame.

For those APIs providing access to data there will also typically include information on what data is provided, its currency and completeness as well as any quality statements. Often information on the data license will also be provided especially for those APIs providing open data.

Some typical examples of different types of API documentation can be seen below.

Zoho CRM API Documentation:

See a live example here: Zoho API

CKAN (Data.gov.ie) API Documentation:

See a live example here: CKAN API

National Transport Authority API Documentation:

See a live example here: NTA API

OPW River Level API Documentation:

See a live example here: OPW API