REST Overview¶

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

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.