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 Caching
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 & Times.

• 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_.

• href (optional): The request URL which returned the error

• 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.

  • detail: A specific English error message for the developer.

  • code (optional): A specific error code for the developer. Each possible code value is enumerated in the particular resource documentation.

  • 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:04z",
    "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": "1234567"},
    "product": {"id": "1234"},
    "customers": [
        {"id": "1234567"}
    ],
}

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "time": "2022-02-02T22:22:22Z",
    "http_status_code": 400,
    "message": "Cannot find a valid tour service on the booking.",
    "href": "https://rest.gadventures.com/activity_services"
    "errors": [
        {
            "field": "booking_id",
            "code": "TOUR_SERVICE_NOT_FOUND",
            "detail": "Cannot find a valid tour service on the booking.",
            "value": 1234567
        }
    ],
    "error_id": "gapi_2ced816b106848dc87b4c7d1a386be21",
}

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.