Timesaver API

Access your timesaver data from any application


Introduction

The Timesaver API is a REST API

VerbDescription
GETRetrieve a resource from the server
POSTCreate a resource
PUTUpdate a resource

Authentication

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

 SyntaxExample
Timesaver ID / passwordBasic <Timesaver ID>:<password> encoded as Base64Basic aW5mb0B0aW1lc2F2ZXIuY2g6dGVzdA==
Fast Login TokenBearer <Fast Login Token>Bearer NDg1OjE1MzgxMzk4NzQ3MTE6MDEzZDlkNWI5ZDY4NDA0N2RiZWE5YTQ2ZTAyYzU5MmVjZjkwNWI3YWU1MDE3YjU1NjUzMzM3YmI1YWM3YmMyOA==
Mandator API keyAPIKey <Mandator API key>APIKey NjMyMDE3ZGQtZTgyYi00ZDE4LTkxYzItMmUzNTU4MWI1MmMzOjE5NQ==

HTTP Response Codes

The following codes are returned by the Timesaver API.

CodeDescription
200OK
201Created
304Not Modified: the HTTP client should use the version that was sent previously
401Unauthorized: access to the requested resource requires an authorization
403Forbidden: valid credentials may have been provided in the request, but those credentials don't grant access to the resource
404Not Found: the resource doesn't exist
406Not acceptable: an unsupported mime type was sent in the Accept header

HTTP Request Headers

Following HTTP headers are interpreted by the server:

NameSyntaxExampleDescription
Accept<mime type>application/jsonThe requested format for the response. application/json is the only recommended type.
AuthorizationSee 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> GMTWed, 06 06 2018 08:43:53 GMTSimilar 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> GMTWed, 06 06 2018 08:43:53 GMTThe opposite of the If-Modified-Since header

HTTP Response Headers

NameSyntaxExampleDescription
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> GMTWed, 06 06 2018 08:43:53 GMTThis 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.chIndicates which autorization schemes are available. See Authentication

Date And Time Formats

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

TypeFormatExampleDescription
Dateyyyy-MM-dd2018-01-25ISO8601 date format
Date and timeyyyy-MM-dd'T'HH:mm:ss'Z'2018-06-29T22:00:00ZISO8601 date and time format. Time zone: UTC
Date and time with millisecond precisionyyyy-MM-dd'T'HH:mm:ss.SSS'Z'2018-12-31T22:59:59.999ZTime zone: UTC

Dynamic Search

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]

OperationType of attributeExample
EqualsNumber, date, date and timefilter.date=2018-06-06
Contains (case sensitive)Stringfilter.street=Hauptstr
Greater equalsNumber date and timefilter.age.begin=34
Smaller equalsNumber, date, date and timefilter.age.end=65

Pagination And Ordering

Pagination and ordering are also implemented using GET parameters

OperationSyntaxExample
Orderingsort=<attribute name>&order=<asc|desc>sort=age&order=desc
Max resultsmax=<max results>max=1000
Skip first resultsoffset=<number of results skipped>offset=2000

Exploring The API