API address structure (URLs)

Every resource of the teamspace API is addressed via a URL. Once you understand how these addresses are built, you can work out most requests yourself – the pattern is the same everywhere.

The five parts of an API address

A typical API address is made up of these parts:

server/api/collection;matrixparameter?query

• server – the address of your teamspace installation, for example https://app1.teamspace.de.
• api – everything that belongs to the API sits under the fixed path segment api.
• collection – the type of resource you are addressing, for example project, time, contact, expense.
• matrixparameter – optional switches placed directly on the path, separated by semicolons (for example to limit or sort the result set).
• query – the classic query suffix after ?, used to filter the collection (for example ?name=alice&date=2000-01-01).

Addressing a collection

When you address a whole collection, the API lists its elements. Matrix parameters and the query control scope and filtering:

server/api/collection;matrixparameter?query
https://app1.teamspace.de/api/time;limit=10;sort=project?date=2022-01-31

This example reads the first 10 entries (limit=10) from the time collection, sorted by project (sort=project) and filtered to the date 2022-01-31.

Addressing a single element

You reach a single element by appending the element ID to the collection:

server/api/collection/itemid;matrixparameter
https://app1.teamspace.de/api/time/123;depth=0

Here the time element with ID 123 is read. The matrix parameter depth=0 controls how deeply nested/linked objects are included.

A collection’s response

When you query a collection, the API responds with an object that contains the matches as items – along with the total count and the page size:

{
  "size": 3,
  "offset": 0,
  "limit": 100,
  "items": [
    { "caption": "Example corp.", "href": ".../api/contact/3456", "value": 3456 }
  ]
}

Each element is a link object with caption, href and value (the ID). Via href you load the full element – you do not need to assemble the URL yourself (HATEOAS, see below).

Filtering collections (query)

You use the query part after ? to filter a collection. You combine several conditions with &:

For values with spaces, use quotation marks ("bob ross"). Example: all contacts whose caption contains “examp”:

GET  https://app1.teamspace.de/api/contact?caption*=examp

Matrix parameters in detail

Matrix parameters sit on the path (separated by ;) and control the scope and shape of the response:

For single elements there is an additional caching parameter:

HATEOAS: linked resources

When one element refers to another (for example a contact to its address), the API returns a link object rather than a bare ID:

"mainAddress": {
  "caption": ";;Examplestreet 7;Examplecity;;122456;Germany",
  "href": ".../api/contactfield/173880993",
  "rel": "contactfield",
  "value": 173880993
}

This is how you follow the chain: from the contact to the address, and on from there. When updating, only the value matters – you do not need to send the whole link object back (instead of subtype: {…}, subtype: "HOME" is enough).

Terms at a glance

Notes

• The collection follows the functional area – the names match the teamspace objects (for example contact for contacts, expense for expense documents).
• Matrix parameters sit on the path and are separated by semicolons; the query comes right at the end after ?. The two can be combined.
• Concrete request and response examples for each resource are provided by the API Compact Guide (PDF & PowerPoint to download).

Related topics

• API – introduction API Introduction
• Create and use a device password (API token) API How-to
• Create a contact via the API API Exercises