Types, Formats and Conventions

HTTP Methods and URLs

In general, an API resource is accessed or acted upon using an HTTP method and a URL. The HTTP methods used are:

• GET - Retrieve an object
• POST - Create an object
• PUT - Update (or create) an object
• DELETE - Delete an object

The general URL scheme is /{resource class}/{id}/{sub resource or operation}, resources denoted in singular form (i.e. /job/123456, not /jobs/123456).

Response Codes

Some commonly used HTTP response codes:

Parameters

Query and form parameters have some common types and follow some conventions listed below.

Media Type

Almost all data is transferred using JSON as the media type. There are some exceptions though, for example some resources that contain dense information more suitable to a tabular format. CSV (comma separated values) are typically used for that.

Unless otherwise stated in the documentation, JSON is used. So you'll typically see this header in the response:

Content-Type: application/json; charset=UTF-8

In case of errors (both client and server ones) you'll simply get a status code and oftentimes a plain text response describing the error.

JSON Content

JSON specifies a pretty clear structure but not how some data types are to be conveyed. So here are some conventions in use throughout the API:

Date and Time

Dates and timestamps are specified as number of milliseconds since January 1st 1970 UTC (the epoch). Otherwise known as UNIX timestamps.

PUT Operations are Patching

All POST/PUT operations affect only the attributes you include (which in some other APIs are a PATCH operation). So for example, if you include only the title attribute when you update a job, only the title is changed and all other attributes remain unchanged.

Common Attributes

This section describes some common attributes that are present in most objects used throughout the API.

Creator

Objects typically contain a creationTimeStamp describing when it was created and a creatorId (which is a user ID) of the creator.

Groups and Sharing

An object can either be private or shared with a group. Private objects are only accessible by its creator (creatorId attribute). Shared objects have a groupId attribute that indicates the group it's shared within. If you don't specify a groupId the object will be shared with the calling user's primary group (primaryGroupId) if the shareAllWithPrimaryGroup flag is set, or the calling API key's primary authorized group (if any).

IDs, UUIDs and Syncing

For historical reasons, relations between objects are specified with both numeric IDs and UUIDs throughout the API.

Referring to Objects

Object relations are often represented both by an ID (i.e. groupId) and an UUID (i.e. groupUuid) in the JSON content. When groupId is mentioned throughout the documentation you may use groupUuid instead.

When creating/updating relations (POST and PUT calls), make sure you don't specify both ID and UUID (especially not conflicting IDs, or else).

Storing References

At some point you probably want to sync some object in Coredination with some object in another system. When storing references to Coredination objects in another system, please use the UUID whenever possible instead of the numeric ID. Numeric IDs may change in the future if we need to make changes to the underlying database infrastructure. Our plan is to eventually remove the numerical IDs from the API and only use UUIDs.

Object Creation

When creating objects, in some cases you can use either POST (and let the server assign ID) or PUT with a client-generated URL path. The latter variant has a significant advantage, especially when used on a mobile device or shaky network: If a request times out and is resent, you won't end up with two objects in case the first request actually was received by the server.

Custom Fields

Custom fields are available on a number of resources, including (but not limited to) jobs, reports and customers. They will typically be represented in the a JSON structure as a list with customFields as the property name.

The JSON representation of a custom field looks something like this:

{
	"internal": false,
	"label": "Person on duty",
	"name": "persononduty",
	"required": true,
	"searchable": false,
	"type": "STRING",
	"typeInfo": "person_name",
	"value": "John Smith",
	"viewPermission": null,
	"weight": 1
}

Types

The following are valid values for the type property:

Type information

The typeInfo field is used to specify how input of the field is to be accepted. For STRING or TEXT fields, it's used mainly to help mobile applications present the right keyboard variant. For SELECT fields it's used to store the available options.

For STRING and TEXT fields, the following typeInfo values have special meanings:

The Coredination applications keep the type information indefinitely, since i.e. jobs don't refer back to their template and thus need their type information anytime a field needs to be changed by a user. The reason for us not referring back to templates is to allow templates to change over time while allowing changes to 'instances' (i.e. jobs) even after a template has changed. The drawback is that type information will be duplicated a lot. So, most importantly, SELECT fields with a lot of options should be avoided if possible. If your application makes use of custom fields and you don't agree with the reasoning above, feel free to remove type information for custom fields when it suits your application. The type information is only used for editing fields within the applications, not presentation.