Request & Response basics

Bedrijfsrooster uses the handy JSON format as default for endpoint requests and responses. This article explains how we standardised our language and how you should process responses.

Requests

Making requests to the API endpoints is easily done using the tools you prefer. Endpoints in general support the POST, GET, PUT, DELETE request methods. Parameters can be provided via the URL QUERY string or as JSON BODY, depending on the endpoint used.

📘
Authorization - OAuth2 & Open ID Connect
Secured endpoints can be accessed by providing an OAuth2 access_token or OpenIDConnect ID Token in the Authorization header. The IAM API handles access_tokens and ID Tokens as the same and issues them identically.

📘
Request Parameters via URL QUERY and/or JSON BODY
URL QUERY string parameters are processed on any request method.
JSON BODY parameters co-exist to parameters in the url query string.
GET requests must not contain a body, they might even be invalidated at load balancer before the API will handle it.
The request Content-Type header must always be "application/json" for the JSON BODY to process successfully.

📘
Request Rate Limiting
Bedrijfsrooster uses Token Bucket based traffic policing to limit requests, which you should take into account with care. In responses that are rate limited you find X-RateLimit-XXX values that can be used to determine your request rate. If you want to be safe, limit your rate to 5 requests per second. You get a time penalty when exceeding rate limits.

📘
Datetime and Timezones
Bedrijfsrooster processes datetime properties that you provide in the timezone of the API User Organization. If you specify a datetime, use the RFC3339 format. Omit the timezone suffix to use the Organization timezone.

Responses

To have a user friendly and widely known response format, the response object style is based on the Google JSON API Style Guide, as you might have experienced using the Google API ecosystem.

A typical response is a JSON object that has some informational properties, either a "success" or "error" property, and optionally a "data" property in which resource data is provided.

{
    "apiVersion": 1,
    "env": "production",
    "meta": {
        "system": {
            "TI_SERVER_TIME": "2019-10-24T11:53:57.263Z",
            "TI_SERVER_ID": "00c61b117c63eed2572e462ee0f003526105a57d627",
            "TI_APP_SERVICE": "timeclock",
            "TI_APP_DEPLOYMENT_ID": "421948540064269098"
        }
    },
    "message": "OK",
    "success": true,
    "data": {
        "kind": "TimeclockBadge",
        "id": 1234,
        "companyGroupId": 5647,
        "companyId": 2048762,
        "companyUserId": 2648792,
        "type": "integer",
        "personFirstname": "Bennie",
        "personLastnamePrefix": "",
        "personLastname": "Bach"
    }
}

{
    "apiVersion": 1,
    "env": "production",
    "meta": {
        "system": {
            "TI_SERVER_TIME": "2019-10-24T11:53:57.263Z",
            "TI_SERVER_ID": "00c61b117c63eed2572e462ee0f003526105a57d627",
            "TI_APP_SERVICE": "timeclock",
            "TI_APP_DEPLOYMENT_ID": "421948540064269098"
        }
    },
    "message": "OK",
    "success": true,
    "data": {
        "kind": "TimeclockBadgeCollection",
        "items": [
            {
                "id": 1234,
                "companyGroupId": 5647,
                "companyId": 2048762,
                "companyUserId": 2648792,
                "type": "integer",
                "personFirstname": "Bennie",
                "personLastnamePrefix": "",
                "personLastname": "Bach"
            },
          	{
                "id": 1235,
                "companyGroupId": 5647,
                "companyId": 2048762,
                "companyUserId": 2648793,
                "type": "integer",
                "personFirstname": "Bert",
                "personLastnamePrefix": "de",
                "personLastname": "Buffel"
            }
        ]
    }
}

{
    "apiVersion": 1,
    "env": "production",
    "meta": {
        "system": {
            "TI_SERVER_TIME": "2019-10-24T11:53:57.263Z",
            "TI_SERVER_ID": "00c61b117c63eed2572e462ee0f003526105a57d627",
            "TI_APP_SERVICE": "timeclock",
            "TI_APP_DEPLOYMENT_ID": "421948540064269098"
        }
    },
    "error": {
      	"code": 401,
        "message": "Unauthorized. The error.code is usually identical to HTTP status header."
    }
}

Depending on your request, the API responds with either a data property containing a single resource or a collection, or an error property. For more details on the JSON style please see: https://google.github.io/styleguide/jsoncstyleguide.xml.