The TeamSnap API is a hypermedia JSON API, using Collection+JSON. There are resources on the web available to describe Collection+JSON (including the official Collection+JSON specification), so this document is only intended as a brief overview, and includes descriptions of TeamSnap API specific Collection+JSON extensions in use in our API.
There are 2 basic principles for Collection+JSON:
Collection+JSON is designed to be inherently discoverable. Each response is always a collection, and each collection always contains all the pertinent actions performable on objects in that collection.
A Collection+JSON client should not construct a URL because the Collection+JSON API makes no guarantee that URLs will remain static for the same actions on the API.
The API guarantees that the rel will remain static (unless there is a major version revision), but the href is subject to change. You should always use the rel to determine what href to follow.
{
"href": "https://apiv3.teamsnap.com/members/search?user_id=695269",
"rel": "members"
}
In the example above, you can see that there are 2 components per link: the rel and the href. In this example, you would find this particular link via the rel members, and then navigate to the href provided: https://apiv3.teamsnap.com/members/search?user_id=695269.
It is sometimes helpful to think of Collection+JSON as a machine-optimized webpage. When you browse the internet, you generally do not construct your own URLs to a page of interest; instead, you click on existing links provided by the website author to navigate the website hierarchy as the website author intended.
Collection+JSON is a RESTful specification. All interactions against the API follow this pattern:
| Action | Verb | |
|---|---|---|
| create | POST | Make a POST request against the href provided in the collection to create an object, using the template specified parameters. Do not include any parameters that are not being set. |
| read | GET | |
| update | PATCH | Make a PATCH request against the href provided for the specific object, using the template specified parameters. Do not include any parameters that are not being updated. |
| destroy | DELETE | Make a DELETE request against the href provided for the specific object |
There are multiple components in a Collection+JSON response body.
Items are the meat of a Collection+JSON response. The items key in the collection body will contain an array of multiple JSON objects, and each object will contain data and a href, and can contain any of the other Collection+JSON components described later.
"items": [
{
"data": [ "..." ],
"href": "https://apiv3.teamsnap.com/users/695269",
"links": [ "..." ]
}
]
In the example above, the items key contains a solitary object, which itself contains data, a href, and links. Data is always specified in key value pairs as follows:
"data": [
{
"name": "id",
"value": 695269
},
]
Each data object will contain a name and value, and can optionally contain a type. The name key represents the key of the key-value pair, while the value key represents the value of the key-value pair.
If a type is present, it will represent the data type of the key-value pair:
{
"name": "updated_at",
"type": "DateTime",
"value": "2014-10-01T09:19:36.000+00:00"
}
In the above example, the type is DateTime and indicates that the value is a DateTime (encoded in ISO 8601 Format).
Links, as described above, indicate related objects that will be of interest. Links can be present in both the items in a collection, and on the collection itself.
"links": [
{
"href": "https://apiv3.teamsnap.com/teams/search?user_id=695269",
"rel": "teams"
}
]
In the example above, the links array only contains one object. For links, the rel is the key and the href is the value of the key-value pair. Since the hrefs are subject to change at any time, it is unwise to construct your own URLs!
Queries are similar to links, in that they represent potential objects of interest. However, a query will require some construction (which is explicitly defined by the query object).
A query will contain a data array, an href, and a rel. As with links, you should rely on the rel to locate the specific query you are looking for.
"queries": [
{
"data": [
{
"name": "id",
"value": null
}
],
"href": "https://apiv3.teamsnap.com/users/search",
"rel": "search"
}
]
In the example above, the queries array contains a single query object. To construct this URL, you must take the href parameter, and then add the data parameters as URL parameters.
If we wanted to query for the user with the id of 40, you would hit the following endpoint:
OAUTH_ACCESS_TOKEN=your_oauth_access_token_here
curl -H "Authorization: Bearer $OAUTH_ACCESS_TOKEN" -X GET https://apiv3.teamsnap.com/users/search -d 'id=40'
If you are not using cURL, you will need to URL encode the parameters:
GET https://apiv3.teamsnap.com/users/search?id=40
As with links, under no circumstances should you modify the href itself or rely on the href to remain static as it is subject to change at any time.
A template is a recipe for updating or creating an object via the API. Each template will contain a data array, which will contain acceptable data to POST or PATCH against the collection or object hrefs.
"template": {
"data": [
{
"name": "first_name",
"value": null
}
]
}
In the template above, it contains a single datum. The client should use this datum to construct POST or PATCH form or multipart body encoded parameters.
Given the following (truncated) collection:
{
"collection": {
"href": "https://apiv3.teamsnap.com/users",
"items": [
{
"data": [
{
"name": "first_name",
"value": "Charles"
}
],
"href": "https://apiv3.teamsnap.com/users/695269"
}
],
"template": {
"data": [
{
"name": "first_name",
"value": null
}
]
}
}
}
If you wanted to create a new user, you would POST against the href specified in line 3:
OAUTH_ACCESS_TOKEN=your_oauth_access_token_here
HREF_OF_COLLECTION=https://apiv3.teamsnap.com/users
# NOTE: The above href should be obtained from the response and not constructed manually.
curl -H "Authorization: Bearer $OAUTH_ACCESS_TOKEN" -X POST $HREF_OF_COLLECTION -d 'first_name=Bob'
and you will receive a response similar to the following:
{
"collection": {
"href": "https://apiv3.teamsnap.com/users",
"items": [
{
"data": [
{
"name": "first_name",
"value": "Bob"
}
],
"href": "https://apiv3.teamsnap.com/users/1234567"
}
],
"template": {
"data": [
{
"name": "first_name",
"value": null
}
]
}
}
}
If you wanted to modify the user instead, you would PATCH against the href specified in the object itself (on line 12):
OAUTH_ACCESS_TOKEN=your_oauth_access_token_here
HREF_OF_OBJECT=https://apiv3.teamsnap.com/users/695269
# NOTE: The above href should be obtained from the response and not constructed manually
curl -H "Authorization: Bearer $OAUTH_ACCESS_TOKEN" -X PATCH $HREF_OF_OBJECT -d 'first_name=Robert'
and you would receive a response similar to the following:
{
"collection": {
"href": "https://apiv3.teamsnap.com/users",
"items": [
{
"data": [
{
"name": "first_name",
"value": "Robert"
}
],
"href": "https://apiv3.teamsnap.com/users/1234567"
}
],
"template": {
"data": [
{
"name": "first_name",
"value": null
}
]
}
}
}
The Collection+JSON spec supports the addition of extensions. These are the extensions in use for TeamSnap's API:
The Command Templates extension allows the discovery of commands in the Collection+JSON response. These commands are generally actions that don't fit cleanly in the normal RESTful responses, such as disabling a user or inviting a new team member.
{
"commands": [
{
"href": "/users/disable",
"rel": "disable",
"name": "Disable",
"prompt": "Disable user",
"data": [{ "name": "id", "value": "", "prompt": "User id to disable" }]
}
]
}
The Type extension allows the specification of a type for any data attribute in the Collection+JSON response.
{
"name": "updated_at",
"type": "DateTime",
"value": "2014-10-01T09:19:36.000+00:00"
}
The Deprecated extension allows for an OPTIONAL deprecated property on items within the data array to indicate that the item is being removed. The value of the property SHOULD be a boolean value of true or false.
data: [
{
"name": "old_name",
"value": "Robert Tables",
"prompt": "'old_name' is deprecated and will be removed in a future version, use 'new_name' instead."
"deprecated": true
},{
"name": "new_name",
"value": "Robert Tables",
"prompt": "Name"
}
]
The Read-only extension informs the client that some collection items are read-only, while still allowing others to be updated and also new items to be created.
{ "collection":
{
"version":"1.0",
"href":"http://example.org/issues/",
"items":[
{
"href":"http://example.org/issues/1",
"read-only":true,
"data":[
{ "name":"title", "value":"some non-updatable issue"}
]
},
{
"href":"http://example.org/issues/2",
"read-only":false,
"data":[
{ "name":"title", "value":"some updatable issue"}
]
},
{
"href":"http://example.org/issues/3",
"data":[
{ "name":"title", "value":"some other updatable issue"}
]
}
],
"template": {(...)}
}
}
The following is an example of a full Collection+JSON response.
{
"collection": {
"href": "https://apiv3.teamsnap.com/users",
"items": [
{
"data": [
{
"name": "id",
"value": 695269
},
{
"name": "type",
"value": "user"
},
{
"name": "first_name",
"value": "Angus"
},
{
"name": "last_name",
"value": "McGillicuddy"
},
{
"name": "email",
"value": "angus.mcgillicudy@example.com"
},
{
"name": "is_admin",
"value": false
},
{
"name": "facebook_id",
"value": null
},
{
"name": "facebook_access_token",
"value": null
},
{
"name": "receives_newsletter",
"value": false
},
{
"name": "birthday",
"value": "1987-05-01"
},
{
"name": "updated_at",
"type": "DateTime",
"value": "2014-10-01T09:19:36.000+00:00"
},
{
"name": "created_at",
"type": "DateTime",
"value": "2012-11-12T17:05:51.000+00:00"
}
],
"href": "https://apiv3.teamsnap.com/users/695269",
"links": [
{
"href": "https://apiv3.teamsnap.com/apn_devices/search?user_id=695269",
"rel": "apn_devices"
},
{
"href": "https://apiv3.teamsnap.com/gcm_devices/search?user_id=695269",
"rel": "gcm_devices"
},
{
"href": "https://apiv3.teamsnap.com/members/search?user_id=695269",
"rel": "members"
},
{
"href": "https://apiv3.teamsnap.com/teams/search?user_id=695269",
"rel": "teams"
}
]
}
],
"links": [
{
"href": "https://apiv3.teamsnap.com/apn_devices",
"rel": "apn_devices"
},
{
"href": "https://apiv3.teamsnap.com/gcm_devices",
"rel": "gcm_devices"
},
{
"href": "https://apiv3.teamsnap.com/members",
"rel": "members"
},
{
"href": "https://apiv3.teamsnap.com/teams",
"rel": "teams"
},
{
"href": "https://apiv3.teamsnap.com/",
"rel": "root"
},
{
"href": "https://apiv3.teamsnap.com/me",
"rel": "self"
}
],
"queries": [
{
"data": [
{
"name": "id",
"value": null
}
],
"href": "https://apiv3.teamsnap.com/users/search",
"rel": "search"
}
],
"template": {
"data": [
{
"name": "first_name",
"value": null
},
{
"name": "last_name",
"value": null
},
{
"name": "password",
"value": null
},
{
"name": "birthday",
"value": null
},
{
"name": "email",
"value": null
},
{
"name": "facebook_id",
"value": null
},
{
"name": "facebook_access_token",
"value": null
}
]
},
"version": "3.12.0"
}
}