Edools API

Overview

This describes the resources that make up the official Edools Core API v1. If you have any problems or requests please contact support.

Current Version
Schema
Parameters
Client Errors
HTTP Redirects
HTTP Verbs
Authentication
Pagination

Current Version

By default, all requests receive the most recent version of the API, at the moment v1. We encourage you to explicitly request this version via the Accept header, because that way when future upgrades occur your application will be requesting the correct API version.

Accept: application/vnd.edools.core.v1+json

Schema

All API access will be over HTTPS, and accessed from the core.edools.com domain (or http://edools-core.herokuapp.com/ for sandbox environment). All data is sent and received as JSON, but we also accept XML.

$ curl -i https://core.edools.com/schools

HTTP/1.1 200 OK
Server: nginx
Date: Fri, 12 May 2014 23:33:14 GMT
Content-Type: application/json; charset=utf-8
Connection: keep-alive
Status: 200 OK
ETag: "a00049ba79152d03380c34652f2cb612"
Content-Length: 5
Cache-Control: max-age=0, private, must-revalidate
X-Content-Type-Options: nosniff

[]

Blank fields are included as null instead of being omitted.

All timestamps are returned in ISO 8601 format:

YYYY-MM-DDTHH:MM:SSZ

Summary Representations

When you fetch a list of resources, the response includes a subset of the attributes for that resource. This is the “summary” representation of the resource. (Some attributes are computationally expensive for the API to provide. For performance reasons, the summary representation excludes those attributes. To obtain those attributes, fetch the “detailed” representation.)

Example: When you get a list of school products, you get the summary representation of each product. Here, we fetch the list of school products owned by the edools school:

GET /school_products

Detailed Representations

When you fetch an individual resource, the response typically includes all attributes for that resource. This is the “detailed” representation of the resource. (Note that authorization sometimes influences the amount of detail included in the representation.)

Example: When you get an individual school product, you get the detailed representation of the product. Here, we fetch the edools/demo product:

GET /school_products/demo

The documentation will provide an example response for each API method. The example response illustrates all attributes that are returned by that method.

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:

$ curl -i "https://core.edools.com/school_products?published=true"

In this example, the :published param is passed in the query string.

For POST, PATCH, PUT, and DELETE requests, parameters not included in the URL should be encoded as JSON with a Content-Type of ‘application/json’, but can be encoded as XML too:

$ curl -i -d '{"status":["active"]}' https://core.edools.com/enrollments

Client Errors

There are three possible types of client errors on API calls that receives request bodies:

Sending invalid JSON will result in a 400 Bad Request response.

 HTTP/1.1 400 Bad Request
 Content-Length: 35

 {"message":"Problems parsing JSON"}

Sending the wrong type of JSON values will result in a 400 Bad Request response.

 HTTP/1.1 400 Bad Request
 Content-Length: 40

 {"message":"Body should be a JSON Hash"}

Sending invalid fields will result in a 422 Unprocessable Entity response.

 HTTP/1.1 422 Unprocessable Entity
 Content-Length: 149

 {
   "message": "Validation Failed",
   "errors": [
     {
       "resource": "Issue",
       "field": "title",
       "code": "missing_field"
     }
   ]
 }

All error objects have resource and field properties so that your client can tell what the problem is. There’s also an error code to let you know what is wrong with the field. These are the possible validation error codes:

missing: This means a resource does not exist.
missing_field: This means a required field on a resource has not been set.
invalid: This means the formatting of a field is invalid. The documentation for that resource should be able to give you more specific information.
already_exists: This means another resource has the same value as this field. This can happen in resources that must have some unique key (such as Label names).

If resources have custom validation errors, they will be documented with the resource.

HTTP Redirects

API uses HTTP redirection where appropriate. Clients should assume that any request may result in a redirection. Receiving an HTTP redirection is not an error and clients should follow that redirect. Redirect responses will have a Location header field which contains the URI of the resource to which the client should repeat the requests.

301: Permanent redirection. The URI you used to make the request has been superseded by the one specified in the Location header field. This and all future requests to this resource should be directed to the new URI.
302, 307: Temporary redirection. The request should be repeated verbatim to the URI specified in the Location header field but clients should continue to use the original URI for future requests.

Other redirection status codes may be used in accordance with the HTTP 1.1 spec.

HTTP Verbs

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

HEAD: Can be issued against any resource to get just the HTTP header info.
GET: Used for retrieving resources.
POST: Used for creating resources, or performing custom actions (such as merging a pull request).
PATCH: Used for updating resources with partial JSON data. For instance, an Issue resource has title and body attributes. A PATCH request may accept one or more of the attributes to update the resource. PATCH is a relatively new and uncommon HTTP verb, so resource endpoints also accept POST requests.
PUT: Used for replacing resources or collections. For PUT requests with no body attribute, be sure to set the Content-Length header to zero.
DELETE: Used for deleting resources.

Authentication

There are only one way to authenticate through Edools Core API.

Token Authentication

$ curl -H 'Authorization: Token token="TOKEN"' http://core.edools.com/schools

The Token will say if you have access to the data of one organization or if you are requesting data of a single school. That way, with a valid token for edools organization, when you make a GET request in http://core.edools.com/schools you will receive the list of all schools that belongs to edools.

Pagination

Requests that return multiple items will be paginated to 10 items by default. You can specify further pages with the ?page parameter. For some resources, you can also set a custom page size up to 100 with the ?per_page parameter. Note that for technical reasons not all endpoints respect the ?per_page parameter.

$ curl 'https://core.edools.com/enrollments?page=2&per_page=100'

Note that page numbering is 1-based and that omitting the ?page parameter will return the first page.

For more information on pagination, check out our guide on Traversing with Pagination.