About Requests & Responses
In the next several sections, we'll introduce some basic details about our servers, request and response structures, and other useful information to help you get up and running.
Host URLS & Resources
Below are the host URLs for our current demo and development environments.
| First Rate Demo Environment | Host/Resource URL |
|---|---|
| API Docs | https://demoapidocs.firstrate.com/api-docs |
| API Reference | https://demoapidocs.firstrate.com |
| API Gateway | https://demoapidocs.firstrate.com:8443 |
Request & Response Structure
API requests take JSON-encoded payloads, query, and path parameters and provide standard JSON-encoded responses. All GET and DELETE API requests take path and/or query parameters, while POST API requests accept a JSON-encoded body. Please note that there might be some exceptions which will be detailed in the API Docs. For some endpoint responses, the JSON body will be presented in a table structure format.
Headers
Below are the headers that are supported for the Demo API calls:
| Header | Mandatory | Description | Example |
|---|---|---|---|
| x-api-key | Yes | API key | secret_test_key |
| x-api-version | No | API version | 1.0 |
| Cache-Control | No | Send with value as no-cache to get latest data | no-cache |
| Content-Type | No | The content type being sent in the request | application/json |
JSON Structure
APIs with volumetric data will send JSON responses back in the form of a table or sheet structure. This structure mimics a database table or a spreadsheet. This allows API users to send/receive data in a very simple JSON format.
POST for GET
At First Rate, we take data security very seriously. To ensure the utmost protection for this data we've implemented a specific design choice: passing all parameters within the request body instead of listing query parameters or path variables in the URL.
How does this help?
- Reduced Logging Risk: By placing this data in the request body, it becomes less likely to be logged by intermediary servers. Many systems only log request URLs and headers, omitting the request body. This significantly reduces the chance of accidental data exposure.
- Enhanced Security: Data within the request body benefits from additional security measures compared to url-based query parameters or path variables.