TeamBeam API Version 2

Getting Started ¶

Transport ¶

The TeamBeam API is available via HTTPS only. The hostname matters, most entities are bound to a specific hostname, and accessing them on other hostnames will often not work.

The base URI for all resources is:

https://{hostname}/api/skp/v2

Authentication ¶

Most requests require authentication in the form of bearer tokens. See authentication.

Some unauthenticated requests may use a cookie-based session.

Rate Limiting ¶

Many resources are protected against misuse or overload caused by badly behaving clients through rate limits according to the Leaky Bucket Algorithm as a Queue concept. Buckets are initially empty. Every request attempts to add a drop to the bucket. If the capacity does not allow this, the request is rejected (see ‘HTTP 509 Rate Limit Exceeded’ in section ‘Error handling’). Buckets drain over time, reducing their specific level and allowing new requests.

HTTP headers inform about the current bucket properties:

• X-RateLimit-Limit

  The total capacity of the current bucket.

  Example:

  X-RateLimit-Limit: 60

• X-RateLimit-Remaining

  The remaining capacity in the current bucket. Once this value is exhausted, future requests will be rejected until the bucket has been drained sufficiently.

  Example:

  X-RateLimit-Remaining: 42

Different resources use different buckets:

API Deprecation ¶

Over time, the backend may change and a new version of the API will be released. To inform developers and clients of upcoming changes, the server indicates API deprecation by sending a Warning header with warning-code 229.

Example:

Warning: 299 - “API Deprecation Warning: Support for this request will be dropped soon, please update your client.”

While API deprecation is indicated, the API call will still function as documented. At a later stage, support for individual API calls up to the complete API-path may be dropped. This is indicated by responding with HTTP status code 410 (see section ‘Error handling’).

Payload format ¶

Unless explicitely stated, request and response bodies are encoded in JSON format. Appropriate headers (Content-Type: application/json, Accept: application/json) must be set.

Timestamps are encoded in ISO 8601 format, including timezone offset from UTC. Example:

{ “validDate”: “2037-12-31T15:29:59+00:00” }

Error handling ¶

The API responds with different HTTP Status Codes and messages:

• HTTP 400 Bad Request

  The request cannot be processed for syntax reasons. This could be because of a missing field, an incorrect type or an invalid value. The error message might provide more information. Check your code against the documentation. Retrying the request will not improve your chances of success.

  Example:

  {
      "error": {
        "code": 400001,
        "message": "The request cannot be fulfilled.",
        "details": ["Invalid or unsupported value.", "Please consult the documentation."]
      }
    }

• HTTP 401 Not Authorized

  Your request is missing an authenticated session ID, your session ID has expired, or your user is not valid. Obtain a new session and/or authenticate it (see the AuthResource).

• HTTP 403 Forbidden

  Your request was syntactically correct, but violated somehing else. Possible reasons are feature- and/or contract-limitations, accessing someone else’s data without authorization. Retrying the request will lead to the same result. The details of the message will provide more details.

  Example:

  {
    "error": {
      "code": 403001,
      "message": "This request is forbidden.",
      "details": ["TTL is not acceptable"]
    }
  }

• HTTP 404 Not Found

  The request could not be fulfilled, since the resource or entity at the URI does not exist (anymore). Retrying is futile.

• HTTP 405 Method Not Allowed

  The resource or entity does not support the HTTP method. Please consult the documentation.

• HTTP 406 Not Acceptable

  The backend cannot supply the response in the requested mediatype (as per the Accept request header). Please consult the documentation. You can retry your request, specifying appropriate headers.

• HTTP 409 Conflict

  The request was not successful, because the a persistence-opertion failed. This can be temporary, or because another operation has modified the data in the meantime. Reread your data again, apply your changes and retry the request. You haven’t broken anything yet.

• HTTP 410 Gone

  The request was once valid but is no longer acceptable. This is a permanent situation. It indicates that parts of the API have since been deprecated and support for them has been dropped. It is recommended to consult the documentation and update clients.

• HTTP 413 Request Entity Too Large

  The backend is unwilling or unable to process a request body of this size.

• HTTP 415 Unsupported Mediatype

  The backend does not support the request payload, as announced in the Content-Type header.

• HTTP 416 Range Not Satisfiable

  This occurs when an upload or download request does not provide acceptable values for headers Range or Content-Range.

• HTTP 429 Rate Limit Exceeded

  The request was not accepted because of a rate limit violation. The API is protected against overload and bruteforce attacks with rate limits. See the section on rate limiting for details. The response contains a Retry-After header (in seconds) to assist in retrying the request again.

  Example:

  Retry-After: 23

• HTTP 500 Server Error

  Oops! It looks like something went horribly wrong in the backend. You might want to get in touch with us.

• HTTP 503 Maintenance

  The host you’re addressing is currently undergoing maintenance and is not serving requests. You can retry your request until is being accepted again.

Authentication ¶

In order to access privileged data or perform actions, the request must use an authenticated session.

Adminunit Resource ¶

An adminunit is the top level entity that combines users, transfers, folders, objects, etc. representing a customer.

All requests must be authenticated with an access token. Administrator privileges are required.