General Implementation Notes

API versioning

Every endpoint starts with /v<x> in which x is the version.

Rate-limits

The number of API calls is limited on an hour basis accross the API
The amount of calls differ between anonymous users and users with an API Token

Special Field Types

Permission Field

Value	Description
`invited_read`	Invited with read-only permission
`subscribed_read`	Subscribed with read-only permission
`invited_write`	Invited with read-write permission
`subscribed_write`	Subscribed with read-write permission
`removed`	Removed

Transport Mode Field

Value	Description
`car`	Travel by car
`transit`	Travel by transit/ public transport
`bicycle`	Travel by bicycle
`walk`	Travel by foot

Inside trip requests combinations of several transport modes may also occur, [transit,walk] is for instance often used to serve door-to-door trips by public transport.

Calendar Type Field

private, webdav, ics & google

Location Type Field

favorite, home & work

Date Time Field

Date format

The date format that should be used is ISO-8601 extended, formatted as YYYY-MM-DDThh:mm:ss.ssssssZ.

An example of valid date format:

"2004-02-12T15:19:21:00.000000Z" // URL ENCODED: 2004-02-12T15%3A19%3A21%3A00.000000Z

Timezone format

For timezones the standard olson timezone definitions should be used (see: http://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

image-URL Field

In order to cope with images being served over both secure (https) and insecure (http) connections, URL fields are expected to begin with "://" instead of "http://" or "https://".

Pagination

To allow to request a limited amount of rows, it is required to send the limit and offset params

Parameter	Type	Required	Default	Description
limit	INT	False	10	Tells to the API the amount of rows that are being requested
offset	INT	False	0	Tells the API where to start returning records from the entire set of results. If you don't include this parameter, the default is to start at record number 0 and then return the number of records specified with the 'limit' parameter.

Offset, limit and count

When requesting an endpoint that supports offset and limit, the response will also contain a count that specifies the total amount of items that could be returned. This count can be used to determine whether all items have been returned, and the amount of necessary pagination needed.

By sending offset=0&limit=0 the count will still be returned, allowing to only request the count for usecases in which the item details are not needed.

Max-limit

Currently the maximum value that can be set for limit is 100, meaning that any endpoint can only be paginated by 100 at the time. Setting the limit to any higher value will return an error.

A note on default offset and limit

As described above, requests will default to repsonding with the first 10 items when no offset or limit are specified. To find out whether all items are returned, the count can be checked inside the meta-data send along with the request.

Furthermore, even when specifying for a specific set of items with for instance the ids parameter, the limit will still default to 10. If you for example retrieve /events/ids=[01,02,03,04,05,06,07,08,08,10,11], only the first 10 items will be returned.

Example:

GET /api/v1/events/?limit=42&offset=0

{
    "data": [<event object i_0>, ..., <event object i_9>],
    "meta_data": {
        "sync_token": 142,
        "count": 42,
        "offset": 0
    }
}

GET /api/v1/events/?limit=42&offset=10

{
    "data": [<event object i_10>, ..., <event object i_19>],
    "meta_data": {
        "sync_token": 142,
        "count": 42,
        "offset": 10
    }
}

Synchronization

To make it easy to just request for resources updated since your last request you can use a sync_token. Within each request the sync_token is added to the meta_data object of the response. When making the next request the sync_token can be added to the query-parameters to request for all changes since the previous request.

Note that the sync_token returned is related to the current state of all the data, it's the responsibility of the client to have requested all the (paginated) data beforehand.

Also note that GET requests will return deleted resources (see Representation of deleted resources), this will allow clients to know which resources have been deleted since the last request.

Example

Step 1: GET /api/v1/events/

All of the events are returned and the current sync_token.

{
    "data": [<event object 1>, <event object 2>],
    "meta_data": {
        "sync_token": 142
    }
}

Step 2: GET /api/v1/events/?sync_token=142

Only the event changed between Step 1, and Step 2 are returned, so in this case event1 is changed, and event3 was added.

{
    "data": [<event object 1>, <event object 3>],
    "meta_data": {
        "sync_token": 144
    }
}

Query evaluation

Query param format

Query parameters are automatically transformed into the specified format. So for example strings should not be surounded by quotes.

Query evaluation

When querying resources using GET requests with query parameters, the query is interpreted by concatenating the query predicates with AND operators.

Thus the following query

GET /tags/?service_ids=[<serviceA>]&calendar_ids=[<calendarX>,<calendarY>]

is interpreted as

GET tags that belong to <serviceA> AND <calendarX> AND <calendarY>

The user of the API must use multiple API calls to simulate queries that require OR operators. E.g. the following query

GET tags that belong to <serviceA> AND (<calendarX> OR <calendarY>)

Needs two API calls as follows

GET /tags/?service_ids=[<serviceA>]&calendar_ids=[<calendarX>]
GET /tags/?service_ids=[<serviceA>]&calendar_ids=[<calendarY>]

The responses of the two requests are then combined to get the full query result.

Representation of deleted resources

Deleting a resource (e.g. DELETE /events/event_id) will only make its content inaccessible, its relationships (e.g. with users) will remain intact. This results in the resource still being returned on GET requests, but only containing its permission and id.

As the deleted resource is still returned, clients can use the information for synchronization purposes (by sending along the Sync token) or use the information to undo a deletion (if allowed).

Deleting a subscription related to a resource instead of the resource itself (e.g. DELETE /subscriptions/subscription_id) will result in making the content inaccessible to the user (or users, in the case of a calendar-event subscription) related to that subscription. Deleting all subscriptions related to a resource will result in the same as deleting the resource itself.

PUT and PATCH Definitions

PUT

A PUT call is a request to replace an object in the server. To perform this action, it is required to send (at least) all required fields having in mind the field type, the field dependencies ( e.g: start < end ). If any of these conditions are not accomplished, the request will return 400 Bad request. All non required fields that are not sent in the call won't be modified at all, leaving the previous value as it is.

PATCH

A PATCH call is a request to change certain fields of the object in the server. To perform this action is required to send only the fields that will change it's value, having in mind the field type and the field dependencies ( e.g: start < end ). Note that setting the value of certain fields can require to send another value because the dependecy between them. ( e.g: start required the start_timezone ). All non required fields that are not sent in the call won't be modified at all, leaving the previous value as it is.