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

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 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 (if POST call is made)
  • in the request body

Data types

  • string
    • {m,M} means minimum m, maximum M characters
    • {N} is a shorthand for {N,N}
  • integer: a whole number, represented as string
  • float: a decimal number, represented as string (with . as decimal separator)
  • boolean: true/false string
  • 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

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
  • X-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
  • 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

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
      • 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!


Last update: September 6, 2020