Resource objects / entity models

Resource objects (or entity models) are JSON objects representing resources / entities in requests to and responses from our API. Resource objects contain attributes of the given entity as well as resource identifier objects which represent relationships with other entities. All properties are in camel-case.

Entity modal for a space

{
	"space": {
		"id": 1,
		"title": "First Space",
		"banner": "",
		"bannerX": 0,
		"bannerY": 50,
		"purpose": "My first space, yay!",
		"code": "fir",
		"isHomepageHeaderEnabled": true,
		"state": "active",
		"spaceColor": "#3d8aed",
		"icon": "chart-line",
		"createdBy": {
			"id": 1,
			"type": "users"
		},
		"createdAt": "2019-10-10T10:40:15Z",
		"updatedBy": {
			"id": 1,
			"type": "users"
		},
		"updatedAt": "2019-10-10T10:40:15Z"
	}
}

Common Fields

Most resource objects will contain the following properties:

id: the unique identifier (integer) for this space (in this example). To fetch this space, you would request GET /v1/spaces/{spaceID}.json (because space is the entity type).

createdAt: when the entity was created. All dates and times follow RFC-3339.

createdBy: the ID of the user who created the entity.

deletedAt: when the entity was deleted. All dates and times follow RFC-3339.

deletedBy: the ID of the user who deleted the entity.

updatedAt: when the entity was last updated. All dates and times follow RFC-3339.

updatedBy: the ID of the user who last updated the entity.

Empty Values

When a property is empty, it will always be returned by the API. It will either be null, [], {}, depending on its type.

Relationships

Properties may contain "resource identifier objects" which are used to denote relationships with other entities. There are to-one relationship which links the current entity to one other entity and to-many relationships which link the current entity to multiple other entities.

Relationships are not guaranteed to be given. They may exist or not, on an endpoint by endpoint basis. The relationship may only exist from the parent side, the child side, both, or may be omitted altogether.

To-One Relationship

A to-one relationship property's value is a resource identifier object which contains an id and type. id is the user's identifier and type is the [entity type](/general/entity-types). If you wanted to fetch this user, you could send [GET /v1/users/1.json`](/api/ref/users/get-v1-users-useridjson). Some endpoints also support including related entities.

To-One Relationship Sample

"createdBy": { "id": 1, "type": "users" },

An empty to-one relationship

"deletedBy": null,

To-Many Relationship

Spaces doesn't currently have any to many relationships defined, but when added, will follow the below convention.

A to-many relationship property's value is an array of resource identifier objects.

All of the items might not be returned, see pagination for more. For each to-many relationship (e.g. comments), there's a corresponding _Count property (e.g. commentsCount) containing the total number of items in the relationship.

To-Many Relationship Sample

{
	...
	"comments": [
		{ "id": 72, "type": "comments" },
		{ "id": 10, "type": "comments" },
		...
	],
	"commentsCount": 5,
	...
}

An empty to-many relationship

"comments": [],
"commentsCount": 0,

Meta Data

For some relationships, there may be metadata. An example would be the object relationship in the notification entity model, which for comments shows the comment type and if it is a reply:

Feedback

If you have any feedback or suggestions, feel free to contact us at api@teamwork.com.

Sample payload showing the comment type is a reply

{
	...
	"id": 19,
		"object": {
			"id": 27,
			"type": "comments",
			"meta": {
				"commentType": "inline",
				"isReply": true
			}
		},
    ...
}