Timesaver API

Access your timesaver data from any application

Introduction

The Timesaver API is a REST API

Verb	Description
GET	Retrieve a resource from the server
POST	Create a resource
PUT	Update a resource

Timesaver supports several authorization mechanisms. Credentials must be sent in the Authorization header.

	Syntax	Example
Timesaver ID / password	Basic <Timesaver ID>:<password> encoded as Base64	Basic aW5mb0B0aW1lc2F2ZXIuY2g6dGVzdA==
Fast Login Token	Bearer <Fast Login Token>	Bearer NDg1OjE1MzgxMzk4NzQ3MTE6MDEzZDlkNWI5ZDY4NDA0N2RiZWE5YTQ2ZTAyYzU5MmVjZjkwNWI3YWU1MDE3YjU1NjUzMzM3YmI1YWM3YmMyOA==
Mandator API key	APIKey <Mandator API key>	APIKey NjMyMDE3ZGQtZTgyYi00ZDE4LTkxYzItMmUzNTU4MWI1MmMzOjE5NQ==

The following codes are returned by the Timesaver API.

Code	Description
200	OK
201	Created
304	Not Modified: the HTTP client should use the version that was sent previously
401	Unauthorized: access to the requested resource requires an authorization
403	Forbidden: valid credentials may have been provided in the request, but those credentials don't grant access to the resource
404	Not Found: the resource doesn't exist
406	Not acceptable: an unsupported mime type was sent in the Accept header
422	Unprocessable Entity: The server understands the content type of the request entity, and the syntax of the request entity is correct, but was unable to process the contained instructions.

Following HTTP headers are interpreted by the server:

Name	Syntax	Example	Description
Accept	<mime type>	application/json	The requested format for the response. application/json is the only recommended type.
Authorization	See Authentication		This header is mandatory for all requests
If-None-Match	<base 64 encoded hash> or <revision number>	MTUyNzc2NTMzOTEzNjoy 0	Used in order to perform a conditional request. For a GET request, the server will respond with a status of 304 not modified if the hash or the revision number of the resource hasn't changed. For other requests, the action will only be performed if the the hash of the resource doesn't match the value sent. Note that the HTTP client should use the value returned by the server in the ETag header in most cases. It should not calculate the hash itself.
If-Match	<base 64 encoded hash> or <revision number>	MTUyNzc2NTMzOTEzNjoy 0	The opposite of the If-None-Match header. Used for example to update a resource only if it wasn't changed.
If-Modified-Since	<day-name>, <day> <month> <year> <hour>:<minute>:<second> GMT	Wed, 06 06 2018 08:43:53 GMT	Similar to If-None-Match and If-Match. The server will respond to a GET request with a status of 304 if the Last-Modified value on the server matches the value sent.
If-Unmodified-Since	<day-name>, <day> <month> <year> <hour>:<minute>:<second> GMT	Wed, 06 06 2018 08:43:53 GMT	The opposite of the If-Modified-Since header

Name	Syntax	Example	Description
Cache-Control	<privacy>, max-age=<max-age in seconds> or no-cache	public, max-age=3600 no-cache	Privacy public indicates that the resource may be stored in any HTTP cache processing the HTTP request and private indicates that only the HTTP client may cache the response. Max-age indicates for how long the resource should be returned from a cache before hitting the server again. If no-cache is used, the resource should not be stored in any cache.
ETag	<base 64 encoded hash> or <revision number>	MTUyNzc2NTMzOTEzNjoy 0	Entity tag. This is a hash identifying the revision of the returned resource. This is used to detect changes on the resource when used in conjunction with the If-None-Match and If-Match request headers.
Last-Modified	<day-name>, <day> <month> <year> <hour>:<minute>:<second> GMT	Wed, 06 06 2018 08:43:53 GMT	This is the last modified time of the resource. This is used to detect changes on the resources when used in conjunction with the If-Modified-Since and If-Unmodified-Since request headers.
WWW-Authenticate	<type> realm=<realm>	Basic realm=timesaver.ch	Indicates which autorization schemes are available. See Authentication

As in any REST request, data are represented in JSON. Here a the accepted format for date and time types.

Type	Format	Example	Description
Date	yyyy-MM-dd	2018-01-25	ISO8601 date format
Date and time	yyyy-MM-dd'T'HH:mm:ss'Z'	2018-06-29T22:00:00Z	ISO8601 date and time format. Time zone: UTC
Date and time with millisecond precision	yyyy-MM-dd'T'HH:mm:ss.SSS'Z'	2018-12-31T22:59:59.999Z	Time zone: UTC

Some resources implement a dynamic search based on GET HTTP parameters. For an example, see Holiday notes.

The parameter names are built following this model: filter.<attribute name>[.operation]

Pagination and ordering are also implemented using GET parameters

Operation	Syntax	Example
Ordering	sort=<attribute name>order<asc\|desc>	sort=age&order=desc
Max results	max=<max results>	max=1000
Skip first results	offset=<number of results skipped>	offset=2000