Responses

• Response Format
• Pagination
• Partial Response
• Compression

Response Format

The Oberplan API will respond to requests with a HTTP status code and a body formatted in JSON.

For a successful request, the response will carry a status code in the 2XX code range, typically 200.

Status codes in the 4XX range indicate a client error, such as 400 for malformed request syntax.

A 5XX status code is returned when the server was unable to perform the request due to a server error.

The response body will include a success flag and, if the request was successful and data is returned, a data property with the requested information:

{
   "data": {
      "color_bk": "#0080FF",
      "id": 7329,
      "name": "Conference Room 2A",
      ...
   },
   "success": true
}

If an API request is unsuccessful, the response body will contain an error property with error details:

{
   "error": {
      "code": "resource_not_found",
      "message": "The requested resource doesn't exist.",
      "resource_type": "resource",
      "status": 404
   },
   "success": false
}

Pagination

If a request returns a list then the result will be paginated.

The response body includes a pagination property which provides paging metadata:

{
   "data": [
      ...
   ],
   "pagination": {
      "limit": 20,
      "links": {
         "first": "https://api.oberplan.com/v1/schedules/1021400/bookings?offset=0&limit=20",
         "last": "https://api.oberplan.com/v1/schedules/1021400/bookings?offset=20&limit=20",
         "next": "https://api.oberplan.com/v1/schedules/1021400/bookings?offset=20&limit=20"
      },
      "offset": 0,
      "page_count": 20,
      "total_count": 28
   },
   "success": true
}

To control the pagination, you can use the offset and limit parameters in the query string. offset determines the starting point for the result set (default: 0), limit controls the amount of entities to return (default: 20, all: 0).

For example, to return 5 items starting with the 10th item, use the following:

Partial Response

By default, an API response includes the full representation of a resource. To reduce bandwidth usage you can retrieve only the fields you need.

To request a partial response, use the fields query parameter to specify the fields you want returned. For multiple fields use a comma delimited list.

Note: The ID of a resource will always be returned.

For example, to return a list with only the id, the name and the last update time of your schedules, use the following:

Compression

By default, the Oberplan API returns response content as uncompressed JSON. Compressing the response is recommended because it will reduce bandwidth usage and improve performance.

To enable compression, include the following HTTP header in the request:

The API will compress the response body and include this header:

Sample request:

curl https://api.oberplan.com/v1/users/me \
-X GET \
-H "Accept-Encoding: gzip" \
-u user@oberplan.com:mypassword