Intro to RESTful APIs

aWhere's API platform is built as REST-based web services. Any application or programming language that connects to and interact with the wider Internet can easily integrate our data. In most current implementations, RESTful APIs are built on HTTP, the same protocol that web browsers use to fetch webpages. This article goes over some of the basic design considerations for RESTful APIs, but there are also other sites with more in-depth overviews as well as language-specific guides:

There are four essential parts to implementing RESTful APIs using HTTP—URIs, verbs, headers and status codes, and payloads. While the rest of this article explains each part, what's important to know is that it is simple to integrate the APIs into your application. The basic transaction is a simple request-and-response. You make a Request to aWhere (retrieving or creating data), and aWhere sends a Response that delivers data or informs you of the results of an action.

Important: You cannot use a normal web browser to access the APIs; instead you'll either need to do some programming, as described in this tutorial or in the sample code, or use an API client like Postman, for which we have some handy pre-built collections.

URIs

Every thing or data element that you request is represented by a URI (or URL). We represent these objects in our documentation like so:

/v1/models
  • Represents a single list of all available growth stage models
/v1/models/AddModelIDHere
  • Represents the details about a single model
/v1/weather?latitude=40&longitude=-95&startDate=2015-05-01
  • Represents the specific weather at a location and time. In our APIs, this is considered a single data point or object that can be requested by URL.

Combine the URI with a hostname, like https://api.awhere.com to retrieve or interact with the data.

The key to understanding this RESTful design is that data is considered an object or a resource, and your application uses the APIs to retrieve that data and do something with it. In older web service architectures (like SOAP), APIs were more action driven. Both approaches can get and change data, but in REST the actual manipulation happens in your application and you essentially save it to the cloud, rather than your application asking the server to do a bunch of work.

Statelessness & Hypermedia

Related to this concept is the fact that RESTful APIs are stateless. This means between one API call and the next, the server doesn't remember your application; all it's doing is responding to discrete requests. While this means you have to identify yourself with every request, it's also a much more lightweight design and easier to work with. It also allows API providers to scale more easily and provide better performance.

Because pieces of data are often interconnected, you may occasionally need to retrieve several pieces to paint a complete picture (meaning several API calls). Though the server won't remember what you asked for last time, we use Hypermedia Links to describe related data. You can simply follow these URLs to retrieve the related data. Related data may include previous/next pages of search results, or a link to the detail of a selected growth stage model.

Our Hypermedia design follows the Hypermedia Application Language (HAL) specification. A tutorial for interacting with HAL is available from PhlyRestfully on Read the Docs.

Verbs

HTTP uses verbs to describe the action you want to take with a URI or piece of data. There are five main verbs—GET, POST, PUT, PATCH, and DELETE. (There are several more verbs defined but these are the primary ones for interacting with our APIs.) We represent the verb in front of the URL (which is how HTTP requests are actually written), like so:

GET /v1/weather

GET requests retrieve data from a server. This is the command that your web browser always uses to retrieve a webpage. The API will retrieve the data you're asking for and return it to you in the API Response.

POST is used for creating data on the server. You should only POST something one time, because if you fire the same request over and over again, the server will create multiple copies that look the same, but will be several unique pieces of data each with their own ID.

PUT and PATCH are used for updating data on the server. PUT is used to replace the data object entirely, whereas PATCH is used to update just a part of a data object. For example, if you have data for a person and their contact information, PUT would be used to change all the fields (address, phone, etc) even if some didn't change. PATCH is used to change only a couple fields, like their phone number or zip code.

DELETE is used to delete something from the server. This can be a true delete or merely hiding the data, depending on the API. But once something is deleted it's gone.

Headers and Status Codes

Every HTTP transaction has headers at the beginning of the message. These are essentially processing instructions or metadata about the request and response. Each header is described by its name and the value, in this format:

HeaderName: Value

Our APIs require some headers such as Authorization to process your request. We will also include a variety of headers your application can use to better understand the request and what else can be done. For example, when you create something with our APIs, we return a Location header with the URL you can use to GET the thing you just created. We also include some headers about your rate limit (described in Conventions), and when results are paginated (like search results), a Content-Range header describes what page you're on and how many total results there are.

We also use Status Codes to communicate with your application. Status Codes are three-digit numbers with a defined meaning, and are included in all responses. 200 OK means the request was processed correctly. Errors that start with a 4 mean there was something wrong with your request. Errors starting with a 5 mean something went wrong in aWhere's system.

You can code your application to handle status codes and adjust its behavior. For example if the API responds with 429 Too Many Requests, it means you're exceeding your rate limit and we need you to slow down. Your application can then wait some time before trying the request again. (The HTTP headers for rate limits will indicate when your rate limit threshold will reset).

Payloads

The payload is the actual meaningful data sent back and forth via the API. When you create something with an API, you send the details in the payload. Whenever an API returns data, it's sent as the payload. The payload can also be called the body of the request or response.

A payload can be any format, including HTML, XML, JSON, plain text, or binary (like image data). aWhere's APIs speak primarily in JSON (JavaScrip Object Notation) which is a lightweight and easily readable format that looks like this:

{
    "property1":"value1",
    "property2":1000,
    "array1":["value1","value2"]
}

The JSON payload describes a data object that you've requested (or created). A data object has a lot of properties; for weather data, that includes the temperature, precipitation, humidity, etc at a particular location at a particular time.

All common programming languages can easily parse JSON into native objects. JSON.org has a good list of available libraries.