Help Center

API Overview

API Overview

The assignr.com application programming interface (API) allows you to programmatically query and make changes to your users, referees, and games.

Since the API is based on REST principles, it conforms to some standard resource-oriented practices for naming conventions and data manipulation. You can use your browser to access URLs, and you can use any HTTP client in any programming language to interact with the API.

Sample Code

We have a couple of very basic API implementations in our GitHub account.

Base URL

All URLs referenced in the documentation have the following base:

https://api.assignr.com/api/v1

Our documentation assumes this base URL as the starting point. So, to get a list of games, when our API documentation describes a URL as /games.json, the full URL is:

https://api.assignr.com/api/v1/games.json

The assignr.com API is served over HTTPS. To ensure data privacy unencrypted HTTP is not supported.

Authentication

The API supports three kinds of authentication:

  • assignr.com Credentials
  • Basic Authentication

assignr.com Credentials

If you are using a web browser, and you are already logged into assignr.com, the API will recognize who you are, and you will be able to query the API by changing your browser URL. This will let you see what the API will return for a specific URL, and is a great way to test it out.

Basic Authentication

This is the next simplest method, and is used when you want to query or update your own data. Most HTTP clients (including web-browsers) present a dialog or prompt for you to provide a username and password for HTTP basic auth. Most clients will also allow you to provide credentials in the URL itself. For example:

https://{username}:{api_key}@api.assignr.com/api/v1/users.json

Your username is the same as your assignr.com user name. Your API key can be viewed on the applications screen:

https://assignr.com/client_applications

Developer Account

If you are developing an that will user another users’s assignr.com data, you should create a developer account. This is a test account that has all of the functionality of a paid account, but is limited to 10 referees.

Rate Limits

All assignr.com requests are subject to rate limits, in an effort to ensure that your use of our API does not negatively impact other users of the system.

The following rate limit rules apply:

  • Maximum of 180 requests per minute
  • Maximum of 500 requests per 5 minute interval
  • Maximum of 5000 requests per hour

You can check the returned HTTP headers for any request to see your current rate limit status:

curl -i https://api.assignr.com/api/v1/users/123.json

HTTP/1.1 200 OK
Date: Thu, 23 Mar 2017 20:47:25 GMT
X-Ratelimit-Limit: 180
X-Ratelimit-Period: 60
X-Ratelimit-Remaining: 178
X-Ratelimit-Reset: 1490302080
X-Ratelimit-Reset-Seconds-Remaining: 35

assignr.com will return information about the rule with the least number of requests left before your request will be blocked.

The rate limit rule can be found in X-Ratelimit-Limit and X-Ratelimit-Period headers. In this example, the rate limit rule is 180 requests in 60 seconds.

X-Ratelimit-Remaining indicates how many requests are remaining before your request will be blocked.

X-Ratelimit-Reset is the time (in UTC Epoch time) at which the current rate limit window will reset

X-Ratelimit-Reset-Seconds-Remaining is the number of seconds until the current rate limit window resets.

If you exceed a rate limit, assignr.com will return a 429 Too Many Requests HTTP error code

curl -i https://api.assignr.com/api/v1/users/123.json

HTTP/1.1 429 Too Many Requests
Date: Thu, 23 Mar 2017 20:47:25 GMT
X-Ratelimit-Limit: 180
X-Ratelimit-Period: 60
X-Ratelimit-Remaining: 0
X-Ratelimit-Reset: 1490302080
X-Ratelimit-Reset-Seconds-Remaining: 35

REST API

If you are new to REST, here’s a few resources from Brian Eng and Jeff Cohen to get you started:

Each resource (Game, User, Age Group, etc) has a similar structure. For example, the API will respond to the following commands for games:

HTTP MethodURL (JSON)URL (XML)ActionDescription
GET/games.json/games.xmlINDEXRetrieve a list of games
GET/games/123.json/games/123.xmlSHOWRetrieve data for game ID 123
POST/games.json/games.xmlCREATECreate a new game
PUT/games/123.json/games/123.xmlUPDATEUpdate data for game ID 123
DELETE/games/123.json/games/123.xmlDELETEDelete game with ID 123

Our API responds to XML and JSON requests, and provides XML and JSON responses.

Search Criteria

You can use the assignr.com search terms to limit the data returned. Our search language can be used to search for specific data in the API.

You will need to URL encode the search terms for the API to interpret the search correctly. For example, the assignr.com search term:

is:unassigned on:"Feb 13"

would translate into the following URL:

/games.json?search=is:unassigned%20on:%22Feb%2013%22

Pagination

If you are requesting a list of resources (e.g. the INDEX action), the resources returned will be paginated, and limited to 50 per request. The data returned will indicate which page number was returned (page), the total number of pages (pages), and the total number of records (count).

To request the next page, use the parameter page

/games.json?page=2  

Request Types

The assignr.com API will respond to one of three request types:

  • application/x-www-form-urlencoded,
  • application/json, or
  • text/xml
PUT /games/123.xml
game[localized_time]=1230&game[localized_date]=2012-05-13

PUT /games/123.json
{"game":{"localized_time":"1230","localized_date":"2012-05-13"}}

PUT /games/123.xml
<game><localized_time>1230</localized_time><localized_date>2012-05-13</localized_date><game>

If your client does not support the PUT and DELETE methods, you can set an HTTP header instead:

X-HTTP-Method-Override: PUT

Response Codes

When you make a request through the assignr.com API, the server will return a response code that indicates whether your request was successful or not. Here are the response codes that we use in our API:

200 OK

Indicates that your request was successful.

201 Created

Indicates that a new resource has been created successfully with a POST command.

400 Bad Request

The request uses incorrect syntax. Most often, this is caused by invalid JSON or XML data.

401 Unauthorized

Valid login credentials are required, or the credentials you provided are not correct.

403 Forbidden

You have provided valid credentials but you don’t have permission to view the resource you have requested.

404 Not Found

Couldn’t find the resource you requested.

409 Conflict

assignr.com uses optimistic locking, which allows multiple users to view the same record for edits, but prevents two users from updating the record simultaneously. Optimistic locking compares the lock_version field that you provide against the record in the database before saving. If the lock_version attributes are equal, the resource has not been changed, and the update can proceed. Otherwise the transaction is cancelled and a 409 error is thrown. Only valid for PUT requests that update existing data.

422 Unprocessable Entity

The request was well-formed but was unable to be followed due to semantic errors. Typically this means that your request failed one or more validation checks, for example, creating a game without a date or time, or creating a new user without a first and last name. Only valid for PUT, POST, or DELETE requests.

429 Too Many Requests

The request exceeded the rate limits imposed by assignr.com. The X-Ratelimit-Reset and X-Ratelimit-Reset-Seconds-Remaining headers in this response will indicate when a request can be retried. See the Rate Limits section above for more information on other rate limit response headers provided by assignr.com.

500 Error

This indicates that an unexpected server error occurred.

503 Service Unavailable

Indicates that we are temporarily unable to respond to your request. Please wait for a bit and try again.