Learn how to effectively use the Try it feature in the API documentation.

Use the **Try it** feature to send sample requests to API endpoints directly from the developer portal. In the **Mock (schema only)** environment, Try it returns schema-driven mock responses or pre-built example responses. In the **Production** environment, it sends the request to the live API and returns dynamic responses from your selected test property.

## Environment

You can select between two different environments (top right corner in the UI):

**Mock (schema only) (default)**:

- Helps to understand the response data schema
- Recommended for all write operations (POST, PUT, PATCH, DELETE)
- Environment for testing without affecting live/test data


**Production**:

- Make sure to use only test properties as the requests hit the production endpoint.
- Changes will affect your test property data
- Requires valid credentials


## Request

Click on any unresolved placeholders to add a value or edit an existing placeholder value.

The portal loads the default request body. Where the specification supports multiple request body examples (for example: Rooms API POST endpoint), you can choose a different request body from the drop-down list.

Some helpful pointers before running a request:

- **Authentication** (when using production endpoint): Configure your authentication headers
  - Bearer token (JWT) as required. Use the **Environments** tab.
  - Make sure to manage separate machine accounts for test vs. properties in production.
  - Ensure credentials match your selected environment.
- **Parameters**: Fill in required parameters
  - Path parameters (like `propertyId`)
  - Query parameters (like `language_code`)
  - Request body for `POST/PUT` operations
- **Execute**: Click **Send** to send the request
  - The request is sent to the selected environment
  - When sending requests to the production endpoint, a real HTTP request is made to the API


## Response

The Try it feature provides comprehensive response information to the extent supported by the OpenAPI specification:

### Status code

- **2xx**: Success responses (200)
- **4xx**: Client errors (400 Bad Request, 401 Unauthorized, 404 Not Found)
- **5xx**: Server errors (500 Internal Server Error)


### Response body

- JSON formatted response data


If the returned response, by default, is unformatted, select the supported Response body format in the UI.

### Response headers

- Content-Type, Content-Length.


## Environments

The **Environments** tab allows you to create variables specific to the environment. For example, you can add a variable to hold the value of the `propertyId` placeholder. The portal inserts the respective value depending on the environment at the time of sending the request.

### Variables

Most of the endpoints (especially POST/PUT/PATCH/DELETE) require you to add a path or query parameter before sending the request. Path parameters use single braces in the OpenAPI specification (e.g., `{propertyId}`). The portal's Environments tab lets you store values for these parameters as reusable variables.

#### Path parameters

- **Required**: Must be provided to make the request
- **Type validation**: Ensures correct data types (integer, string, etc.)
- **Example**: `propertyId` in `/properties/{propertyId}/resource`


#### Query parameters

- **Optional**: Usually have default values
- **Example**: `language_code` with `en-us` as the default value


#### Request body

- **Schema validation**: Follows OpenAPI schema definitions
- **Example data**: Prepopulated with sample values


## Best practices

This section provides some basic practice guidelines.

### Authentication

- Always use separate machine accounts for test properties vs. properties in production.
- When testing with the production endpoint, make sure to use only test properties.


### For Read operations (GET)

- GET requests are non-mutating, but use authorised test properties when testing against the production endpoint.
- Use valid IDs that exist in your system
- Check response structure for integration planning


### For Write operations (POST, PUT, PATCH)

- **Always use Mock (schema only) environment first**
- Verify request payload structure
- Check response for success confirmation
- Test error scenarios with invalid data


### For Delete operations (DELETE)

- **Preferable to use Mock (schema only) environment only**
- Understand the operation is irreversible
- Have backup data when testing using test properties


## Troubleshooting

### Common issues

**401 Unauthorized**

- Check authentication credentials
- Verify token is valid and not expired
- Ensure credentials match the selected environment


**400 Bad Request**

- Validate request payload against schema
- Check required fields are provided
- Verify data types match specification


**404 Not Found**

- Confirm the resource ID exists
- Check the endpoint URL is correct
- Verify you have access to the resource


### Getting help

If you encounter issues:

1. Check the response error message for details
2. Verify your request matches the API specification
3. Contact the Connectivity Team for support


*This documentation applies to all endpoints in the API. The Try it feature provides a consistent testing experience across all operations.*