An Introduction to REST

Background

The Dock411 API is “RESTful”; that is, it is based on the REST architectural style. “REST” stands for Representational State Transfer. It’s a means for different computer systems on the Internet to interoperate.

While there’s no official REST standard, many people working on REST APIs have developed common approaches and best practices that help define how RESTful APIs should work. Many of these guidelines and recommendations are laid out in Apigee's “Web API Design”, by Brian Mulloy. We also recommend you refer to What Is REST’s? six specific constraints or design rules.

As you encounter and work with with different REST APIs, you’ll find most are not fully compliant with the ideal, including the Dock411 API; however, we follow most of the practices and common definitions of the style. For example, the Dock411 API follows the convention of using the standard HTTP POST, GET, PUT, PATCH, and DELETE methods as verbs to act on “resources”, or nouns, like “docks” or “weigh stations”.

You may see these standard HTTP methods referred to as “CRUD”, or Create, Read, Update, Delete. Although CRUD has roots in database operations, you can also map those operations to the standard HTTP methods. For example, use a POST request to create a new resource, a GET request to read or retrieve a resource, a PATCH or PUT request to update a resource, and a DELETE request to delete a resource.

RESTful Features of the Dock411 API

Nouns

In a RESTful API, the entities in a system are called resources. They are the nouns or things in your system that other systems can access or update. For example, the Dock411 API includes the following resources: docks, dock assessments, big box stores, rest areas, weigh stations, among others.

Endpoints

One of the attractive features of REST is that it uses standard HTTP concepts like URLs and URIs. In a RESTful API, the URL indicates which resource you wish to act upon. For example, if you want to access docks, use the URL https://api.dock411.com/v3/docks. To access a particular dock, use the URL https://api.dock411.com/v2/docks/{id} where {id} is the unique identifier of the particular dock you’re interested in.

These URLs are commonly referred to as “endpoints”.

Verbs

At some point you’ll realize most, if not all, endpoints in a well-designed API do not include any verbs. The rationale is that endpoints should only contain resources, or things, and verbs can’t be things. Actions are indicated through the standard HTTP methods. One disadvantage of this approach is that, if one only looks at an endpoint, it does not give enough information to indicate what will happen when it's requested.

For example, the endpoint https://api.dock411.com/v3/truck_stops/{id} gives no hint about if it will retrieve, create, update, or delete that particular truck stop. The actual action is specified through the HTTP method passed with the request and that method is not visible without specialized development tools. In our view, the benefits of using RFC/W3C Standard HTTP codes far outweighs the slight inconvenience of not knowing prima fascia what action will be taken.

Answers

We respond to every request you make to our API. We can’t guarantee you’ll always like the response, but at least you’ll always receive one.

Just as we use standard HTTP method codes to indicate what action to take on a request, we use standard HTTP response codes to indicate our response. Note that we use only a few of the many available response codes.

Getting Started

Now that you know a bit more about the REST architecture and how we use it in the Dock411 API, be sure to contact our API Team to request an API Key then check out the API Reference to start making requests.