The pointercrate API

This is the documentation for the pointercrate application programming interface (short: API). If you dont know what an API is or have no idea how you even got to this page, this link takes you back to the demonlist. If you rather want to read source code of the implementation directly, head over to the github repository instead. It also contains the markdown files these documentation pages are generated from, so if you find any error here feel free to submit a pull request!

The API can be used to retrieve data about the demonlist and is internally used to manage it. All endpoints described here are located under https://pointercrate.com/api/v1/ unless a different api version is explicitly provided, in which case the v1 part of the URL needs to be amended. Currently, there are only a few endpoints using a v2 scheme.

It is always good practice setting the Accept header in requests to application/json (or at least give application/json a higher preference than text/html), so that in case of errors, you receive a JSON response instead of the HTML error page.

All HTTP traffic is automatically redirected to HTTPS. All requests to URLs without a trailing slash are automatically redirected to URLs with one.

Errors

In case of a client or server error, the API returns an error response. Errors that are specific to a given endpoint are always listed in that endpoint’s documentation. Following is an exhaustive list of errors that can occur at any endpoint in the API. Note that the errors with status code 500 INTERNAL SERVER ERROR should (obviously) not occur and are only listed for completeness sake. An complete list of all errors can be found at the bottom on this page.

In the case that you do not receive any response at all, or receive a Apache/Nginx error page you can assume that the pointercrate server crashed and couldn’t recover. If this is the case all hope is lost.

409 versus 412

The cases in which a 409 CONFLICT error or a 412 PRECONDITION FAILED error is returned are very similar. In fact, handling for both errors should probably be identical. A 409 error is returned if the request you were making contained a valid hash of the object you were trying to access, however the same was true for another concurrent request. Which ever of the requests commits its database level transaction might now receive the CONFLICT error. A 412 error means that a modification to the object you were trying to access happen at some point prior to your current request (or the hash you sent along was invalid in the first place).

Both cases need to be handled the same way: You’ll have to re-GET the object to retrieve its updated ETag and retry the request (simply retrying after a 409 error will most likely yield a 412 error directly after)

Authentication

Basic

Some endpoints in the API require you to authenticate using HTTP Basic Authentication. Since all communication with the API is enforced to be done via HTTPS, this is OK.

Access tokens

Pointercrate requires you to have a valid access token to issue requests to most endpoints. An access token for your account can be retrieved via a successful call to the login endpoint.

Pointercrate access tokens are JSON Web Tokens and can be parsed by any standard compliant implementation.

Each access token is valid until you change your password, or is invalidated via a call to invalidate.

When an endpoint requires authentication via an access token, the Authorization header has to be set to the word Bearer followed by a space, followed by your access token.

Cookies

Theoretically, it is possible to authenticate using cookies. Any requests made from your browser through the web interface are authenticated this way. Practically, you cannot use this authentication method (attempting to do so will simply result in a 401 UNAUTHORIZED response)

Errors

These error conditions apply to any endpoint that require authentication and are thus not repeated for every one of them.

Permissions

Different endpoints require different kinds of permissions to be used. Additionally, access to user objects via the sub-endpoints of /users/ is also governed by permissions. In particular, you can only access accounts of users who have permissions that you can assign (with the exception of people having MODERATOR privileges, who can access all user accounts).

If an endpoints requires special permissions to be accessed, it’s documentation will contain a notice similar to this one:

A user’s permissions are saved as a bitmask, and by default every user has no permissions.

Available permissions

The following permissions exist. If a permissions A implies some other permission B, then a user with permission A can do everything a user with permission B can do, without needing to explicitly having the bit for permission B set. For example, a user with only the LIST_MODERATOR bit set also has all privileges that the LIST_HELPER bit grants. Note that implication of permissions in transitive, e.g. a user with only the LIST_ADMINISTRATOR bit set still has all privileges that the LIST_HELPER bit grants, since LIST_ADMINISTRATOR implies LIST_MODERATOR, which implies LIST_HELPER.

If a permission A assigns some other permission B then a user with permission A can modify the bit for permission B via PATCH /users/user_id/ of users he has access to.

Errors

These error conditions can occur at any endpoint expecting requiring specific access permissions and are thus not listed specifically for each of them.

Pagination and Filtering

Some endpoints in the pointercrate API support or require pagination due to the potentially huge amount of data they can return. This mostly applies to the endpoints that return lists of objects, like GET /records/.

Objects returned by endpoints supporting pagination are totally ordered by an ID field, which is specified in the endpoint’s documentation.

If an endpoint supports pagination, it’s documentation will contain a notice similar to this one:

Pagination Query Parameters

Pagination is done via specific query parameters, which tell pointercrate which part of the result set to return.

Note that there is no way to get the total amount of pages, as both page bounds and size can be chosen abitrarily.

Omitting before or after, which implicitly sets them to null, makes the server act like they’re set to negative/positive infinity respectively.

Pagination Response Headers

Paginatable endpoints provide the Links header to simply access to the next, previous, first and last page, using the limit set on the request. The header is set to a comma-seperated list of links in the form <[link]>; rel=[page], where page is one of next, prev, first or last.

Note that the next and prev links are only provided if there actually is a next or previous page of results respectively. The server always provides the first and last links.

Filtering

Most endpoints that support pagination also support filtering their results beyond simply using the pagination parameters.

If this is supported, the documentation specifies the filterable fields for a given endpoint. It is then possible to specify conditions in the query string, which the returned objects must meet.

There are two ways of filtering the result set:

• Filtering by equality: The objects returned can be filtered by a specific field’s value by specifying the field and a value in the query string, i.e. /api/v1/players/?banned=true
• Filtering by inequality: The objects returned can be filtered by whether a field is smaller/greater than a specific value by specifying the field, suffixed with either __lt or __gt, and the value to check for inequality against in the query string, i.e. /api/v1/records/?progress__gt=75. Note that this doesn’t work for all fields (since a lexicographical filtering on the record status hardly seems useful)
• Filtering by infix: Some string-values fields support filtering objects where said string field contains a specific infix. This is done by suffixing the field’s name with _contains.

Multiple conditions can be combined, i.e. /api/v1/records/?after=200&limit=10&status=APPROVED&progress__lt=100. This request would return the first 10 approved records with a record ID greater than 200 and a progress less than 100.

Note that filtering explicitly on the ID field is not possible. You have to use the special before and after parameters for that. You also cannot use equality filtering on the ID field. Use the specific endpoint for retrieving single objects instead.

Errors:

These error conditions can occur at any endpoint supporting pagination and are thus not listed specifically for each of them.

External Videos

Valid video formats

Pointercrate only accepts videos from a specific set of hosting services. It further normalizes all videos from a given host into one specific URL format and ensures that every video link actually leads to a valid video. All query parameters, including timestamps on youtube videos, are stripped from URLs.

If a host you want to see supported is missing or a URL format for one of the provided hosts is missing, please open an issue on the GitHub repository.

Please note that pointercrate asynchronously performs HEAD requests to any video URL submitted and discards any that don’t return a successful response.

The accepted URL formats are:

They are normalized into the following:

Errors

These error conditions can occur at any endpoint expecting a video URL and are thus not listed specifically for each of them.

List of Errors

In general it is the goal to have the API provide as detailed errors as possible. The generic error variants should be returned as rarely as possible. If you feel like a specific error could be communicated better, feel free to open an issue in the GitHub repository!