Intro to the Sandbox APICopy link

A sandbox is a controlled and isolated environment designed for developers to safely discover, test, and interact with an API without affecting production data. A sandbox environment can be used

• As a playground to learn about our connectivity APIs
• As an integrated testing environment when developing and testing their own API integrations
• As the environment for API certification purposes

Currently, our sandbox environment supports the following:

• Reservation management capability
• Notifications (webhooks)

Thus, to simulate traveler behavior, you can create reservations within the sandbox environment and then test the requests (queries and mutations) provided by the Lodging Supply GraphQL API. Refer to Testing your implementation for workflows.

Here are the queries and mutations provided by the Sandbox API:

• property query
• properties query
• reservations query
• cancelReservation mutation
• createProperty mutation
• createReservation mutation
• deleteProperty mutation
• deletePropertyReservations mutation
• deleteReservation mutation
• updateReservation mutation

Endpoints

Here are the endpoints you will be using to test your implementations in the sandbox:

• Sandbox OAuth2 token service endpoint:

  Enables partners to obtain an access token for the Sandbox API.

  https://api.sandbox.expediagroup.com/identity/oauth2/v3/token

• Sandbox API endpoint:

  Creates sandbox data in the state required to run test scenarios and gives partners access to operations not typically available from a supplier standpoint, such as creating reservations.

  https://api.sandbox.expediagroup.com/supply/lodging-sandbox/graphql

• Sandbox LSGQL API endpoint:

  Provides the same queries and mutations as the Lodging Supply GraphQL QPI so that partners can issue requests against properties and reservations in the sandbox.

  https://api.sandbox.expediagroup.com/supply/lodging/graphql

• Sandbox Payments API endpoint:

  Enables partners to retrieve payment information for reservations in the sandbox environment.

  https://api.sandbox.expediagroup.com/supply/payments/graphql

All requests must be made over a secure connection. All response bodies, including errors, are encoded in JSON. If no response is returned within 65 seconds, the request has timed out; set your retry logic accordingly.

Authentication and authorization

This API uses OAuth2 for delegating access to resources. Rather than passing username/password credentials with each request, you can periodically obtain an access token from the OAuth2 server to send within API requests in the form of a bearer token header. The token is used to authenticate and authorize access to the specified property.

If you issue a request using an expired token, an error is returned stating that the token is invalid. We recommended that you retrieve a new token several seconds before it expires to avoid any service disruption. (The expires_in attribute in the response indicates the number of seconds a token is valid.)

If you are calling the API from multiple servers, you can request a unique access token from each server and save it in memory. It is not necessary to persist the token to disk and attempt to reuse across all servers in your application. This should simplify your solution and is potentially more secure as the token is less likely to be compromised if it is not persisted to disk.

Obtaining an access token

To obtain an access token, complete these steps:

1. Contact your Engagement Manager to obtain API credentials, which will be used to authenticate with the OAuth2 token service. Ensure that these credentials are stored securely and are not exposed to your users through cookies, web storage, browser or mobile applications, and so on.

2. Encode the username and password to Base64 by following the OAuth2 standard requirements.

3. Send a POST request to the sandbox's OAuth2 token service (https://api.sandbox.expediagroup.com/identity/oauth2/v3/token). The Content-Type header is required, and grant_type must be specified as a separate data parameter (shown below) or it must be included in the URL.

   Note that the access token's length may vary and additional attributes will be present in the response. Also, the expires_in attribute indicates how long the token is valid (in seconds). This value will change, so be sure to obtain the actual value of the field returned to you and use it to determine the expiration status of your token (and dynamically refresh the token based on expires_in).

4. Save the access token in a secure fashion (preferably in-memory), and do not expose the token to your users in any way. Do not attempt to parse the contents of the access token because they are subject to change. Always send the token directly to the API over a secure TLS connection using server-to-server communications.

Here is an example request to obtain a token:

curl --request POST \
--url 'https://api.sandbox.expediagroup.com/identity/oauth2/v3/token?grant_type=client_credentials' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic {`{base64_encoded_credentials}'`} \
--data grant_type=client_credentials

Example response:

{
  "access_token": "oVapAccHHYCGzggNaVHP.ys7dffRkOP2om9Hkbylo.tssKms0UIo9KScLlegv1",
  "token_type": "bearer",
  "expires_in": 1799, 
  "scope": "lodging-supply.property-status.get"
}

Calling the API with an access token

After you obtain an access token, you must include it with all API requests; every request must be authenticated, no anonymous access is allowed. Pass the token in the header of requests as follows:

Authorization: Bearer {token}

If you have a valid token, your request is processed by the API. Otherwise, an error is generated indicating that the token has expired or is invalid in some way.

HTTP headers

Here are the request and response headers for calls made to the Sandbox API.

Request and response headers

Because the API is used over HTTP, standard headers that are part of the HTTP specification and industry standard extensions are returned as part of the response.