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.
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
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.
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.
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
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:
- API root (p:root)
- Agencies (p:agencies)
- Agency (p:agency)
- Booking Agent (p:booking-agent)
- Booking Check (p:booking-check)
- Branch (p:branch)
- Branches (p:branches)
- Floating data (p:floating-data)
- Infocard (p:infocard)
- InfoCards (p:infocards)
- Journey (p:journey)
- Location (p:location)
- Locations (p:locations)
- Mode (p:mode)
- Modes (p:modes)
- On-trip planner (p:ontrip-planner)
- Password reset (p:password-reset)
- Product (p:product)
- Products (p:products)
- Registration (p:registration)
- Reservation (p:reservation)
- Routes (p:routes)
- Transit stop time (p:stoptime)
- Transit stop times (p:stoptimes)
- Subscription (p:subscription)
- Subscriptions (p:subscriptions)
- Trip (p:trip)
- Trip alternatives (p:trip-alternatives)
- Trip in progress (p:trip-in-progress)
- TripLeg (p:trip-leg)
- Trip registration (p:trip-registration)
- Trip registrations (p:trip-registrations)
- Trip selection (p:trip-selection)
- User (p:user)
See RFC 6906 for more information about profiles and how they interact with media types.
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:
- Agency (r:agency)
- Agency branches (r:agency-branches)
- Available products (r:available-products)
- Booking Agent (r:booking-agent)
- Booking Check (r:booking-check)
- Agency (r:branch)
- Branch products (r:branch-products)
- Favorite routes (r:favorite-routes)
- Floating data (r:floating-data)
- Geocoder (r:geocoder)
- Reverse geocoder (r:gedeocoder)
- Geodecoder Bounding Box (r:geodecoder-bbox)
- Geodecoder Bounding Circle (r:geodecoder-bcircle)
- Infocards (r:infocards)
- Journey (r:journey)
- Location (r:location)
- On-Trip planner (r:ontrip-planner)
- Operator (r:operator)
- Owned modes (r:owned-modes)
- Owner (r:owner)
- Password (r:password)
- Password reset (r:password-reset)
- Trip planner (r:plan)
- Products (r:products)
- Product branches (r:product-branches)
- Registration (r:registration)
- Reservation (r:reservation)
- Routes (r:routes)
- Service Provider (r:service-provider)
- Stop times (r:stoptimes)
- Subscription (r:subscription)
- Subscriptions (r:subscriptions)
- Suggested locations (r:suggested-locations)
- Trip (r:trip)
- Trip in progress (r:trip-in-progress)
- Trip Leg (r:trip-leg)
- Trip registration (r:trip-registration)
- Trips (r:trips)
- Trips calendar (r:trips-calendar)
- User agencies (r:user-agencies)
See RFC 5988 for more information about links and link relations.
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