Skip to content

Overview

Jump to bottom
Tyler Knappe edited this page Mar 30, 2015 · 4 revisions

Conventions

Camelcasing

Although TeamSnap's API uses snake-casing (e.g. tracked_item_status), TeamSnap.js converts everything into camelcase (trackedItemStatus) to follow general JavaScript conventions. You will never see any snake-cased methods, types, commands, etc. as it gets converted on load and send.

Callbacks and promises

TeamSnap.js asynchronous methods support both the Node.js callback style or the jQuery (and other) promises style of handling asynchronous methods.

Callbacks

TeamSnap.js asynchronous methods all take callback as the last argument in regular Node.js style. This is a callback function with the signature function (err, result) { ... } which will be called when the operation is complete.

teamsnap.loadTeams(function(err, teams) {
  if (err) console.error(err);
  else console.log(teams);
});

Promises

In addition to accepting a callback argument, asynchronous methods also return a promise in order for your code to use promises instead of callbacks. A promise is an object with methods on it that allow you to respond to certain outcomes of the code. For mor information about promises in general, see http://davidwalsh.name/write-javascript-promises and http://www.mattgreer.org/articles/promises-in-wicked-detail/. Once nice thing about promises is they can be chained, and the results of previous handlers are passed on to the next handlers. And if a handler returns another promise, this "pauses" the chain until it is finished, allowing for much more readable chains of asynchronous actions.

teamsnap.loadTeams().then(function(teams) {
  console.log(teams);
}, function(err) {
  console.error(err);
});

// chained example
function loadTeamMembers(team) {
  return teamsnap.loadMembers(team.id).then(function(members) {
    team.members = members;
    return team;
  }
}

teamsnap.loadTeam(1234).then(loadTeamMembers).then(displayTeam).fail(showError);

Collections and Items

The TeamSnap API follows the Collection+JSON format adding an extention for Commands. This allows the API to be self-documenting and reduce breaking changes. Because of this, TeamSnap.js works in Collections and Items, though you don't need to know how it works to use the TeamSnap.js.

Collections

There is a collection for each data type (e.g. teams, members, and trackedItems). You can think of them as database tables. Each collection will have a template if it allows items to be saved to it. This template provides all the fields which are allowed when saving an item to the collection. The collections will have links to other collections or resources related to it. The collections may also provide queries and commands. Queries are ways to search the data within the collection, and commands are actions which can be triggered to run, such as sending an email reminder.

There is a collection at the root of the API with links to all other collections. After TeamSnap.js is authorized, it loads each of the collections linked off the root collection. This provides TeamSnap.js all the templates, links, queries, and commands that it will need to load and save data.

You may access all loaded collections at teamsnap.collections[collectionName]. Collections provide the following methods:

Collection

  • save(item) Saves an item to the collection (will create a new item if it has no href)
  • loadItems(linkName) Loads an array of items using the link linkName
  • loadItem(linkName) Loads an item using the link linkName
  • queryItems(queryName, params) Loads an array of items using the query queryName and the provided parameters
  • queryItem(queryName, params) Loads an item using the query queryName and the provided parameters
  • exec(commandName, params) Executes a command using the command commandName and returns an array of items if the command returns any

Items

If collections are like database tables, items are like the rows in a database table. Each item has a unique href field which can be used to load (or delete) that item. Each item has links to other items by href, showing the relationships between them. All of the load methods in TeamSnap.js return items or arrays of items. When saving an item to its collection, only the fields listed in the collection's template will be sent to the server, so any other data stored on the item will not be persisted.

Items provide the following methods:

Item

  • loadItems(linkName) Loads an array of items using the link linkName
  • loadItem(linkName) Loads an item using the link linkName
  • delete(params) Deletes an item, passing the parameters when provided, returning nothing

Links, Queries, and Commands

Links

Collections and items both have links. The links in an item are particularly useful as they can be used to load (or link if already loaded) an item's related items. For example, you can load all of a member's availabilities by going to the url at member.links.availabilities.href, or programmatically member.loadItems('availabilities').then(...).

Load, create, save, and delete

Generally using the collection and item methods is not necessary, as TeamSnap.js provides a method for every action that can be taken with the API. These cover every item, query, and command. The following is a general list of these methods (e.g. teamsnap.loadAssignments(teamId).then(...)).

We will use "assignments" as the example, but these apply to most item types.

teamsnap

  • loadAssignments(params) Loads the given item type by provided parameters, such as { memberId: 123 }.
  • loadAssignments(teamId) Loads the given item type by teamId. This does not apply to items that don't belong to teams (e.g. timeZone). This is a shortcut to loadAssignments({teamId: teamId}).
  • createAssignment() Returns a new item of the given type immediately. This is not asynchronous.
  • saveAssignment(assignment) Saves an item of the given type. If validation fails, the callback/promise will be called with the error. You may check for this using if (err instanceof TSValidationError) or the existence of a field property.
  • deleteAssignment(href) or deleteAssignment(assignment) Deletes the item provided or the item by the provided href.

The create*, save*, and delete* methods are not available for certain types such as timeZone, plan, and sport as these are read-only collections. In addition, some types are automatically created and deleted by the system and can only be saved, such as availability, trackedItemStatus, and customDatum.

There are methods for each command, and custom methods of the above for a specific type (e.g. teamsnap.deleteEvent(event, include) allows deleting a whole series of repeating events). Detailed documentation on each method will be provided elsewhere.

Clone this wiki locally