REST Overview

The G Adventures API is made of Resources. Each resource represents a logical data container accessible via an endpoint (URI).

Formats

The following data formats are supported for all requests and responses from the API. To specify which format you’d like returned, use the HTTP/1.1 header field Accept. To specify the body format for POST or PUT/PATCH requests, use the HTTP/1.1 header field Content-Type.

Data Format Content-Type Accept
JSON application/json application/json
XML application/xml application/xml

Supported HTTP Status Codes

HTTP Status Code Description
200 OK No errors produced
201 Created New resource successfully created
301 Moved Permanently A permanent redirect - the URL provided in the Location field of the response header should be used for future requests
400 Bad Request The request cannot be complete due to bad syntax
401 Unauthorized Authentication problem with the request
403 Forbidden Insufficient permissions to the requested resource
404 Not Found The resource requested does not exist
405 Method Not Allowed The resource requested does not support this method
406 Not Acceptable The resource requested is only capable of generating content not acceptable according to the Accept headers sent in the request
410 Gone The resource requested is no longer available and will not be available again
424 Failed Dependency The resource is dependent on an unavailable resource
429 Too Many Requests Requests have been rate limited due to too many requests in a given period. See rate-limits
500 Internal Server Error A fatal error occurred on the G Adventures servers while your request was being processed
502 Bad Gateway The server received an invalid response from an upstream server
503 Service Unavailable The server received an invalid response from an upstream server
504 Gateway Timeout The server did not receive a timely response from an upstream server

For further details about each supported HTTP status code, please consult the W3 Status codes in HTTP document.

Errors

Additional details about specific 400 errors are listed in the documentation for each individual resource.

A dictionary of values is always returned in addition to the HTTP status response. Some values are optional and may be null (or empty list):

  • http_status_code: The HTTP status code of the error.

  • time: The time the error occurred, in the standard dates-time.

  • message: A general English error message that could be presented to the end user.

  • error_id: An ID tied to the error event. This value is a hex string sometimes prefixed with gapi_.

  • errors (optional): A list of specific errors geared towards the developer. Multiple errors may be returned at once for efficiency of validation. This list will be empty for non-400 errors.

    • code: A specific error code for the developer. Each possible code is enumerated in the particular resource documentation.
    • detail: A specific English error message for the developer.
    • field (optional): The input field that caused the error.
    • value (optional): The value of the input field that caused the error.

XML Schema: error_message.xsd

Example GET Error:

GET /bookings/555/ HTTP/1.1
Host: rest.gadventures.com
Accept: application/json
HTTP/1.1 404 Not Found
Content-Type: application/json
{
    "http_status_code": 404,
    "time": "2013-08-27T13:39:04",
    "message": "Not found",
    "errors": [],
    "error_id": "gapi_8cef0f3ad5e54ad2bab20493b896ef9f",
}

Example POST Error:

POST /activity_services/ HTTP/1.1
Host: rest.gadventures.com
Accept: application/json
Content-Type: application/json

{
    "booking": {"id": "628099"},
    "product": {"id": "5804"},
    "customers": [
        {"id": "1322842"}
    ],
}
HTTP/1.1 400 Not Found
Content-Type: application/json
{
    "http_status_code": 400,
    "time": "2013-08-27T13:39:04",
    "message": "Activity service can only be added to a tour service.",
    "errors": [
        {
            "message": "Activity service can only be added to a tour service.",
            "code": "SERVICE_IS_NOT_A_TOUR",
            "field": "departure_service_id",
            "value": "1234567890",
        }
    ],
    "error_id": "d8e99656794747c8a75256364f93c7ea"
}

Supported Request Methods

Method Description
GET Retrieves the specified resource
POST Creates a new resource based on the parameters provided
PATCH Updates an existing resource based on the parameters provided

NOTE: PUT requests are analogous to making a PATCH request, as we do not support full replacement of objects as per the PUT spec.

Pagination

Any response which contains a list of results will contain a variety of keys to help determine how you can act on the result set. For example, let’s observe a snipped response to a request on the tour_dossiers resource.

Example response:

{
    "count": 1486,
    "max_per_page": 50,
    "current_page": 1,
    "results": [
        ...
    ],
    "links": [
        {
            "href": "https://rest.gadventures.com/tour_dossiers?page=2",
            "rel": "next"
        }
    ]
}

The total amount of items in the result are available via count. Within links you will be provided objects containing links to paginate between the results.

When there are no available pages, links will be empty. When you’ve hit the last page of the result set, you’ll notice there will no longer be a link with a rel of “next”.

If you’d like to view more results per page, simply send max_per_page as a query parameter with your desired amount.

NOTE: We cap max_per_page to a value between [10, 100] and the default value of 50. If an invalid value is provided for max_per_page, GAPI will respond with a 400 Validation Error

NOTE: Please be aware that count is in some cases only approximate value, even if it is correct it can change as you are paging through results. Therefore to determine the exact number of results always evaluate the results attribute and use the presence of next attribute as an indicator if more pages are available.

Caching

Store G Adventures API responses in your application or on your site if you expect a lot of use. For example, don’t try to call the G Adventures API on every page load of your website landing page. Instead, call the G Adventures API infrequently and load the response into a local cache. When users hit your website, load the cached version of the results. Use Webhooks to update your local cache in order to maximize efficiency and always have up-to-date data. This is particularly beneficial for departure availability updates.