Data Interchange Formats

Field Names

All field names MUST be formatted as camel case (e.g. “givenName”).

Shortened, abbreviated, or otherwise condensed forms of terms should be avoided. Use “phoneNumber” instead of “phoneNo” or “phoneNum”; “speed” instead of “spd”, etc.

Well-known and recognized shortened versions of terms are acceptable and sometimes preferred. For example, “maxSpeed” instead of “maximumSpeed” and “employeeId” instead of “employeeIdentification”

Field Values

Optional fields that have not been set to a value MUST NOT be returned in responses. For example, if a person is created using only a surname, the response to a GET includes only the surname field.

Data Into APIs (bodies of POST’s, PUT’s)

All APIs that accept a body SHOULD accept that body formatted as JSON. APIs MAY accept bodies in other formats.

Clients SHOULD supply a Content-Type header to specify the format of the included body. If no Content-Type header is supplied, the API MUST assume and process the body as JSON.

Data From APIs (bodies returned from GET’s, POST’s, PUT’s)

All APIs that return structured data SHOULD be able to return that data formatted as JSON at a minimum and as the default.

All APIs that return images SHOULD be able to return that data formatted as JPEG at a minimum. APIs MAY return other image formats in response to a content type specified in the query Accept header.

Clients may use the Accept header in the HTTP request to request resources be returned in formats other than those above. APIs SHOULD accept application/json or image/jpeg in the Accept header. Any other format supported by the API SHOULD be one of the recognized Media Types (e.g. application/xml), or a custom media type documented in Trimble-Specific Media Types. If the API does not support any of the formats listed in the Accept header, the API MUST return a 406 “Not Acceptable” (see Error Code table).

If a requester does not include an Accept header, the requester is telling the server it can accept any media type. In this case, Trimble APIs MUST respond with the appropriate format from the Default Content Types table.

All API responses MUST include the Content-Type header in all responses.

Summary of required, default content types

APIs SHOULD support the following, in both requests and responses, if applicable: