Documentation


Overview | Postman | OAuth | Endpoints

 

Overview

This describes the official Schooltas API v1. If you have any problems or requests please contact support.

  1. Current Version
  2. Schema
  3. Parameters
  4. Endpoints
  5. Errors
  6. HTTP Verbs
  7. Authentication
  8. Roles and permissions
  9. Pagination

Current Version

The current version is v1.

Schema

All API access is over HTTPS, and accessed from the api.schooltas.net domain. All data is sent and received as JSON.

Blank fields are included as null instead of being omitted.

All timestamps are returned in ISO 8601 format:

yyyy-MM-dd'T'HH:mm:ssZZ

Parameters

Many API methods take optional parameters. For GET requests, any parameters not specified as a segment in the path can be passed as an HTTP query string parameter.

GET https://api.schooltas.net/v1/users/1337

In this example, the 1337 value is provided for the :id parameter in the path.

GET https://api.schooltas.net/v1/users?organization=42&type=Publisher

In this example, the :organization and :type parameters are passed in the query string.

For POST and PUT requests, parameters not included in the URL should be encoded as JSON with a Content-Type of ‘application/json’.

PUT https://api.schooltas.net/v1/users/7
{
  "firstName": "James",
  "lastName": "Bond",
  "organization": {
    "id": 1,
    "type": "Distributor"
  }
}

Endpoints

You can read the Endpoints chapter to get all the endpoint categories that the API supports.

Errors

HTTP status codes

The following HTTP status codes are used by the Schooltas API. See Wikipedia for detailed information.

HTTP status

HTTP Verbs

Where possible, the Schooltas API strives to use appropriate HTTP verbs for each action.

Verb Description
GET Used for retrieving resources.
POST Used for creating resources.
PUT Used for replacing resources or collections.
DELETE Used for deleting resources.

Authentication

Requests that require authentication will return 403 Forbidden. To authenticate you need to send an OAuth2 token in a header.

$ curl -H "Authorization: Bearer OAUTH-TOKEN" https://api.schooltas.net

Read the OAuth chapter for detailed information.

Roles and permissions

The actions a user can do against the Schooltas API are limited by its permissions. A permission is a combination of an operation and a resource, for example: create book. The permissions of a user are built up by all the permissions of the roles of the user.

When an organization is created it receives a default set of roles. Please contact support if you need organization specific roles. A user can only receive roles of its own organization.

Pagination

When you make an API request to an endpoint which return multiple results, you will usually not receive all of the results of that request in a single response. This is because some responses could contain thousands of objects so most responses are paginated by default.

The Schooltas API uses cursor-based pagination. Cursor refers to a random string of characters which mark a specific item in a list of data. Unless this item is deleted, the cursor will always point to the same part of the list, but it will be invalidated if an item is removed. Therefore, your app shouldn't store any older cursors or assume that they will still be valid.

When reading an endpoint that supports cursor pagination, you will see the following JSON response:

{
  "results": [
     ... Endpoint data is here
  ],
  "paging": {
    "nextCursor": "E-ABAIICGWoJYXBwZW5naW5lcgwLEgVUQm9vaxjIAQwU"
  }
}

A cursor-paginated endpoint supports the following parameters:

Name Type Description
limit number This is the number of individual objects that are returned in each page. Note that this is an upper limit, if there are not enough remaining objects in the list of data, then less than this number will be returned. All endpoints have an upper maximum on the limit value, for performance reasons.
cursor string This is the cursor that points to the start of the page of data that has been returned.

Cursors can't be stored for long periods of time and expected to still work. They are meant to paginate through the result set in a short period of time.