Skip to content

Introduction

Prerequisites

To access EduBase API services, you need the following:

  • an EduBase account
  • registered API application (connected to the user)
    • application ID
    • application secret

Obtain API credentials

To obtain your API application ID and secret key, login to EduBase with your account and go to the Integrations page. Create an API application or view your existing one. If you lack of permissions to create integrations, please contact us.

Warning

Do not share API credentials with anyone.

Endpoints

Endpoints are constructed from the following informations:

  • https://
  • EduBase domain name (e.g www.edubase.net)
  • /api
  • *optional: version specification /vXX*
  • endpoint path (e.g /test:app)

Putting them all together, a request URL is created:

https://www.edubase.net/api/v1/test:app

Warning

Some endpoints require special features to be enabled (either on user or global level). Additionally, endpoints may also be protected by policies. Please contact us if you repeatedly receive authorization errors (e.g 403/406 response status code).

Versions

A call version can be specified for each request separately. There are 2 possible ways:

  • recommended: in the endpoint URL
    • /vXX where XX can only be numeric
  • as call argument
    • add version=XX argument to API call, XX can be a numeric value or a string

If requested endpoint does not support the selected version (or the version does not even exist), an error will be thrown.

Methods

The API service supports GET, POST, PUT, PATCH and DELETE requests. However, not all endpoints implement all of them. Please refer to the endpoint's specification before calling it.

Arguments

Warning

Do not forget to send app and secret API credentials. They are always required.

Endpoints may require or allow to send additional input parameters. These can be sent in:

  • as REQUEST parameter
  • as POST data
  • in the request body

Data types

  • string
    • {m,M} means minimum m, maximum M characters
    • {N} is a shorthand for {N,N}
  • string/null: a string formatted string or NULL if not set
  • integer: a whole number, represented as string
  • float: a decimal number, represented as string (with . as decimal separator)
  • boolean: true/false string
  • boolean/null: a boolean formatted string or NULL if not set
  • date: YYYY-MM-DD formatted string
  • date/null: a date formatted string or NULL if not set
  • datetime: YYYY-MM-DD HH:ii:ss formatted string, in UTC
  • datetime/null: a datetime formatted string or NULL if not set
  • list{type}: a list (array) of type elements
  • list: a hash (associative array) of named elements

Info

JSON-encoded outputs will represent data with their native type (if supported by JSON), instead of strings. For example a boolean will be represented as boolean.

Response codes and output

Response

API service may return status, headers and data:

  • HTTP response status code
  • EduBase-API-Error header (with an error description or code)
  • plain text
  • JSON-encoded text (Content-Type is set to application/json)

Possible HTTP response codes

  • 200: success
  • 400: incorrect endpoint is called or request could not be served temporarily
  • 401: invalid/missing credentials or assume token is invalid
  • 403: endpoint is found, but arguments are not properly set or permission is denied for requested action
  • 405: HTTP request method is not supported
  • 406: incorrect version is selected, endpoint is not available for current API client application or configured limit has been reached
  • 429: too many requests, configured rate limit has been exceeded
  • 500: call is valid, but there was an unexpected error while processing it
  • 501: endpoint and arguments might be correct, but feature is not yet implemented
  • 503: service is temporarily unavailable (e.g maintenance mode is active), try again later

Debugging

For debugging purposes EduBase API returns EduBase-API-Error header in most cases with more detailed error description than the status code. Refer to that message to resolve the issue or contact us for additional help.

Language

Some calls rely on the context language. This defaults to the caller (or assumed) user's language, but can be overridden by sending the EduBase-Language header containing the desired language code (in ISO 639-1 format). Invalid or inactive languages will be ignored.

Rate limiting

API applications may be rate limited (calls/second or calls/minute). Please get in touch with us to learn more about active limits.

Notation

Endpoints in this documentation will be formatted the following way:

  • endpoint path
    • request method and path
      • [] input
        • mandatory fields are marked with [!]
        • watch out for data types
      • [] output
        • JSON if not specified explicitly
        • might be empty if an error occured

For API development and testing we recommend the following applications:

Tip

As always, you can also use curl!