Go About API

Go About has a resource-based API that uses the Hypertext Application Language (HAL) media format. HAL provides a standard way for expressing the resources and relationships of an API as hyperlinks. With HAL, you use HTTP methods (GET, PUT, POST, DELETE) to submit requests and receive information about the API in the response. Applications can use the information returned to explore the functionality of the API.

For more information about HAL, see its Home Page or the Internet Draft.

Terminology

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

Other terms can be found in the glossary

Tutorial

The docs for every profile contain an example for its usage, but only for the profile itself. This chapter tries to give examples for default use-cases that you will encounter. For example: logging in and getting information about the user, planning a trip for the user after querying the geocoder, etc.. This will be a good place to start exploring the API. If you already know what you are looking for (except for droids, the droids that you are looking for are elsewhere), skip over to the profiles or relations section.

Reference

A HAL-based API is defined by three elements: the URI of the root resource, the resource types, or profiles, and the relations that tie them together.

Root resource

The root resource is the only resource that is located by its URI. Its main purpose it to provide links to the different API components. Getting the root resource if often the first thing a client does when using the Go About API. See the description of the API root (p:root) profile for detailed information about the resource content.

The URI of the root resource is https://api.goabout.com.

Profiles

Although the HAL media type defines syntax, it says nothing about what state properties are returned or how to interpret them. Every resource has a profile that describes its semantic type. For example, a resource with the User (p:user) profile represents a user.

Profile names are namespaced URIs, with base http://profiles.goabout.com. For example, the profile of a User resource is http://profiles.goabout.com/user. (A profile URI doubles as a URL to the relevant section in the API documentation, so you can access it in the browser for more information.)

The API documentation uses CURIE abbreviated links to improve readability. The CURIE p is used as shorthand for the profile namespace. So when the documentation mentions profile p:user, it refers to http://profiles.goabout.com/user. (The API does not use CURIEs in responses.)

The API uses the following profiles:

See RFC 6906 for more information about profiles and how they interact with media types.

Relations

The API is explored by following links, not unlike the World Wide Web. Links are distinguished by their relation. For example, the Trips (r:trips) relation connects a user to a list of their previous selected trips.

Relation names that are plain words are registered in the IANA Linked Relations registry and retain their original meaning. For example, the self relation comes from RFC 4287 and signifies the URI of the resource itself.

API-specific relations names are namespaced URIs, in the same way as profile names, with base http://rels.goabout.com. The CURIE for relations in the documentation is r.

The API uses the following Go About-specific relations:

See RFC 5988 for more information about links and link relations.

Authentication and authorization

The API uses the OAuth 2.0 Framework to authenticate and authorize clients and users. The Logging in tutorial contains a section on authentication.

Anonymous access to the root resource will yield links to the Authorization and Token endpoints. No other resources are accessible without some form of authentication.

The Client Credentials Grant flow is used to authenticate clients.

A user accessing the API through a client, or giving access to their data to a client, is authenticated using the Authorization Code Grant flow.

What links are provided between resources is in part based on the authorization used when accessing the API. For example, because only a user can select a trip, the Trip alternatives (p:trip-alternatives) resource only contains a Trip selection (p:trip-selection) link if a user is authenticated.

Information below needs to be expanded

  • URI templates are used where applicable.
  • All date-time values are in ISO 8601 format. If no timezone information is included (or is ‘Z’), they are in UTC.
  • The API supports Cross Origin Resource Sharing for AJAX requests.
  • Unless stated otherwise: all posts are done in JSON, posting with the wrong mediatype will result in a HTTP/1.1 415 Unsupported Media Type