Back to API overview

The swiss unihockey APIs

Version 0.0.0

Swiss unihockey offers REST APIs with the base url of https://api-v2.swissunihockey.ch.

Some of the resources will only be available to registered partners of Swiss Unihockey. These resources are marked as 'private'.

Please get in contact with our IT (it@swissunihockey.ch) if you want to use this API in your own apps.

For details on versioning, please see the changelog.

Authentication

All consumers of this API need a consumer key and a consumer secret. You can obtain these by applying for access at this address.

To authenticate your requests when accessing private endponts, you need to provide an authorization token. Acquire a token by sending your api key and secret to /bo/session/auth. Do not forget to urlencode both key and secret (any '+' in your Token should be converted into '%20' and so on)! See the example on how to do this in your shell.

Example (bash)

KEY="<your api key>"
SECRET="<your api secret>"
curl -v -v --data-urlencode "api_key=$KEY" \
  --data-urlencode "secret=$SECRET" -X POST \
  "http://127.0.0.1:5000/bo/session/auth"

Include this token as parameter auth_token on all of your further requests.

Errors

If an API call results in an error on the server, a corresponding http status code is returned with an error message. Error codes will be from the 4xx or 5xx range, depending on whether we consider the client or the server to be in error.

The error document returned looks like this: 

{
  "object": "error", 
  "data": {
    "message": "ERROR MESSAGE", 
    "code": 123
  }
}

The error code data/code will correspond to the HTTP status code that was returned. The error message (data/message) will - as far as possible - be a localized message that can be displayed to the user. If localisation of the message is not possible, the message will be in the main language.

Staging environment

Is located at https://api-staging.swissunihockey.ch

Versioning

Version information is kept as MAJOR.MINOR where major version number is increased on breaking changes and minor version number is increased on all visible changes.

Major versions will be announced to all partners of Swiss Unihockey. We will give implementors time to prepare for the switch to the new version. The old version will continue running for some time. (end of life)

Minor versions will not be announced. Here's a list of things that can change in minor versions:

  • Existing calls can return a different amount of data, reflected by TABLE/ATTRIBUTE LIST header information changing and the data changing accordingly. Mostly these changes will mean more columns appear. If you render the TABLE structure correctly, no change to your code will be needed.
  • New calls can be added.

Current version is kept current at the top of this document and as part of the return value of /api. Major version number is also kept as part of the DNS name.