Responses in the Firstup Partner API use RESTful response bodies in order to be descriptive and predictable. Each endpoint includes its own documentation illustrating the responses and errors expected, but this section describes the typical responses you can expect to encounter.
Every response provides the following special response headers:
- X-Program-Id: the program id of the scope of the request.
- X-User-Id: the user id of the acting (authenticated) user.
Endpoints that return data will always wrap that data in a "data" property, whether the response data is an object or array.
Successful responses that return data always wrap their data in a "data" property and include a “meta” object at the root level when meta information is available (see below).
While different endpoints use different response codes that correspond to the purpose and design of the endpoint, the following are general patterns you can expect:
- Reading of data in either list or individual form uses 200 OK.
- Creating new records uses 201 Created if a record was created immediately, and 202 Accepted if a record will be created but cannot be completed immediately.
- Updating existing records uses 200 OK if the record was updated immediately, and 202 Accepted if the update will be performed but cannot be completed immediately.
- Executing actions on existing records (such as “archive” or “publish”) uses 200 OK if the record was updated immediately, and 202 Accepted if the update will be performed but cannot be completed immediately. In some cases, if the action does not need to respond with any data, 204 No Content indicates immediate success without a response body.
- Deletion of records or data uses 200 OK if the data was deleted immediately, and 202 Accepted if the update will be performed but cannot be completed immediately.
Each endpoint will describe the response statuses it returns.
Every successful response provides metadata relating to the response in the root of the response body. The meta property includes information that helps to explain the aspects that went into determining what data to return in the response, including pagination, filtering, and sorting.
For endpoints that allow pagination, the metadata includes a pagination property. The page property includes values used in pagination even if the request did not specify a page.
For endpoints that use page pagination, the following properties are provided:
- page_size: The coerced or defaulted page size value from the request.
- page: The coerced or defaulted page number value from the request.
- total_records: A count of the total items in the collection according to the filters.
For endpoints that use cursor pagination, the following properties are provided:
- page_size: The coerced or defaulted page size value from the request.
- cursor: The cursor used for the current set of records.
- next: The cursor to use for the next set of records.
For endpoints that allow filtering, the metadata includes a filters property. The filters property includes default values used in filtering even if the request did not specify filters. For example, if a filter such as “status” is set to “registered” by default, the filter’s property will include status: “registered”.
For endpoints that allow searches, the metadata includes a search property that indicates the value of the search parameter used in the request. If the search property was reformatted or transformed in any way, it will be represented in the meta object in its transformed format.
For endpoints that allow sorting, the metadata includes a sort property that indicates the list of sort keys used in order.
Including page size, total records, cursor, filtering, etc.
Pagination Overview
Includes page number, size, cursor, start index and count.
Filtering Overview
Includes enum based, equals based, timestamp, any property, multiple properties, multiple values and errors.
All errors (4xx and 5xx) response bodies will be wrapped in an “error” structure containing the following fields:
code(the numeric error code).title(the name of the error).detail(a description providing additional information). For example:
`{
"error": {
"code": 403,
"title": "Unauthorized Access",
"detail": "<Message about authorization>"
}
}`Some errors include additional data fields containing information about the error. For example, a validation error will contain a validations field as shown below:
`{
"error": {
"code": 400,
"title": "Bad Request",
"detail": "One or more request validations have failed. The request cannot be completed unless all validations are passed.",
"validations": [
{
"code": "required",
"detail": "Title is required",
"parameter": "title"
}
]
}
}`Error codes in the range 400 - 499 indicate invalid input or improper use of the API. Clients should alter their request to correct the indicated error before trying the request again.
| Status Code | Description |
|---|---|
| 400 | Bad Request: A request parameter or formatting does not match an expected required format. Typical cases include: Missing a required parameter. Invalid formatting of a parameter, such as providing a timestamp filter where the parameter value cannot be coerced to a date or time. Page number or size is not in valid range. Validation errors include an additional validations parameter that contains an array of validation entries specific to individual parameters in the request. Each entry has the following format: code detail parameter |
| 401 | Unauthenticated: Returned when a required access token is not provided. See “Authentication and Authorization” for details. |
| 403 | Forbidden: The Authenticated User does not have permissions required to perform the action requested. |
| 404 | Not Found: Returned when a primary resource is not found. A primary resource can be defined as resource scoped in the URL of the endpoint. For example, the URL channels/123/content/456 results in 404 if the channel or the content doesn't exist, or if the content exists but is not associated to the channel. Additionally, requests for contextually private resources may return 404 as a way to avoid revealing the presence of the resource. |
| 409 | Conflict: Returned by some endpoints when attempting to use or update an identifier that is already taken by another record in that collection. |
| 429 | Too Many Requests: Returned when the rate limit is exceeded. The rate limit is 1,000 requests per minute, per program. A delay and a retry is recommended. |
Error codes in the range 500 - 599 indicate an error on the server. Clients should retry their request again later, or contact support for assistance.
| Status Code | Description |
|---|---|
| 500 | Internal server error |
| 504 | Request timeout |