API Documentation
Overview
The Scoilnet API provides a comprehensive search API for the resources in the scoilnet database. The API provides authentication and authorization via OAuth 2.
OAuth 2 Authentication and Authorization
Scoilnet supports the industry standard OAuth 2 protocols for authentication. Scoilnet uses a custom grant policy (http://scoilnet.com/grants/apikey) similar to Client Credentials but with the use of an API Application key instead of username and password. We have also provided an SDK for php which you can download here to handle the OAuth2 authentication.
Search Requests
The search api will return a list of resources filtered by search keywords and facets. The search results will also return the list of facets with the count of resources for the individual facets. Only public resources will be shown. The following request parameters will be permitted.
| Paramater | Value | Type | Description |
|---|---|---|---|
Content-type | Application/json | String | Content type of the request |
Authorization |
| string | Add Auth token to the header |
q |
| string | Optional. The search keywords |
school_level | int/string | Optional. Filter results by school level. For multiple options separate values with a comma e.g. school_level=1,2,4 | |
school_grade | int/string | Optional. Filter results by school grade. (called level in scoilnet) .For multiple options separate values with a comma | |
school_discipline | int/string | Optional. Filter by discipline (subject) .For multiple options separate values with a comma | |
school_topic | int/string | Optional. Filter by strand (topic). For multiple options separate values with a comma. | |
school_subtopic | int/string | Optional. Filter by strand unit (sub topic). For multiple options separate values with a comma. | |
resource_language | int/string | Optional. Filter by resource language | |
resource_type | int/string | Optional. Filter by resource | |
limit | 20 | int | Optional. Number of resources to return. Default is 20. Max is 50. |
sort | score/creation_date | string | Optional. Sort the results by relevance or last created. Default relevance |
page |
| int | Optional. Show results for a page. You must calculate how many pages there are, based on total result and limit per page. |
lang | en/ga/fr/de | string | Optional. Language of the text results and facets. Default is en. Fall back will be to English. |
fieldset | Default/full | string | Optional. The resource data returned. Default will return a minimum amount of data. Full will return all the data for a resource. |
Single Resource Request
Request a resource by its id
/?resource=21 | Parameter | Value | Type | Description |
Content-type | Application/json | String | Content type of the request |
Api-key |
| string | Client ID |
Authorization |
| string | Add Auth token to the header |
resource |
| int | The resource id |
Response Codes
The scoilnet api uses standard HTTP response codes to indicate the status of requests. Common response codes that the client app should expect include:
| Status Code | Meaning |
|---|---|
200 - OK | The request has succeeded. |
400 - Bad Request | The request was invalid. This response code is common when required fields are unspecified, formatted incorrectly, or invalid filters are requested. |
401 - Unauthorized | The request authentication failed. The OAuth credentials that the client supplied were missing or invalid. |
403 - Forbidden | The request credentials authenticated, but the requesting user or client app is not authorized to access the given resource. |
404 - Not Found | The requested resource does not exist. |
500 - Server Error | The server failed to fulfill the request. Please notify support with details of the request and response so that we can fix the problem. |
Error Responses
Most errors will be 40x response codes and they will return json encoded error message. The json formats consists of 2 different formats.
1. OAuth2 error response formats:
{"error":"" ,"error_description":""}Example:
{"error":"invalid_grant","error_description":"The access token provided has expired."}2. All other API resources will be in the format
{"success":false, "code":400, "message":""}Example:
{"success":false,"code":400,"message":"Sort param field can’t be found: creationDate"}