===== Content Types =====
SCL API is based on RESTful which supports a bunch of different request/response formats, including XML, JSON and serialised PHP. By default, the class will check the URL and look for a format either as an extension or as a separate segment.
^ Format ^ Content type ^
| xml | application/xml |
| json | application/json |
| jsonp | application/javascript |
| serialized | application/vnd.php.serialized |
| php | text/plain |
| html | text/html |
| csv | application/csv |
Default API output content type is json, the following examples is to change output content type
This means your URLs can look like this:
http://example.com/api/v1/dashboard.json
http://example.com/api/v1/dashboard?format=json
This can be flaky with URI segments, so the recommend approach is using the HTTP Accept header:
$ curl -H "Accept: application/json" http://example.com/api/v1/dashboard
===== Login & Retrieve accessCode =====
To access any of API methods you will need retrieve your access token which you will use later for in HTTP Headers for every method call.
Supported request to Auth method is GET
**To retrieve accessCode & User Information**
''%%http://example.com/api/v1/auth?%%identity=Email&password=Pass&objectId=ParseObjectId''
==== Auth Parameter ====
^ Paramater ^ Description ^
| identity | Login Email |
| password | Login Password |
| objectId | This optional for Mobile App with Push Notification need to register Parse objectId |
==== Auth Response ====
^ NAME ^ DESCRIPTION ^
| email | User Email Address |
| full_name | User Full Name |
| group_id | User Group ID, 2 for Parents Group & 4 for Students Group |
| student_code | Student Code is available for Parent & Student only |
| secondary_code | Parent Secondary code for different school division |
| accessCode | API Access code to send in header for every method call |
make sure to add accessCode to your ACCESS-CODE header in every method request.
accessCode is revoked once user changing password or from profile management, in this case you need to be sure that on error code 1050 or 1051 show login screen again for allowing the recreation of new valid accessCode.
===== Authentication =====
To authenticate you must set header name "ACCESS-CODE" to the user retrieved [[api:main#login_retrieve_accesscode|accessCode]]. in order to call any other functions such as student or parent you must always set the header for any method call.
**Curl Example**
$ curl -X POST -H "X-ACCESS-CODE: user_accessCode" http://example.com/api/v1/
**jQuery Example**
$.ajaxSetup({
headers: { 'X-ACCESS-CODE': 'user_accessCode' }
});
OR
$.ajax({
url: 'http://example.com/api/v1/dashboard',
headers: { 'X-ACCESS-CODE': 'user_accessCode' }
});
===== User =====
Calling user information method is GET action & must be [[:api:main#authentication|Authenticated]].
**URL Example**
''%%http://example.com/api/v1/%%user''
^ NAME ^ DESCRIPTION ^ Type ^
| email | User Email Address | String |
| full_name | User Full Name | String |
| group_id | User Group ID, 2 for Parents Group & 4 for Students Group | Integer |
| student_code | Student Code is available for Parent & Student only | String |
| accessCode | API Access code to send in header for every method call | String |
| avatar | image URL of user avatar | String |
| grade_name | Student Grade name, is only show for Student user group | String |
| class_name | Student Class name, is only show for Student user group | String |
| class_description | Student Class Description, is only show for Student user group | String |
===== User Avatar =====
Calling user information method is POST action & must be [[:api:main#authentication|Authenticated]].
**URL Example**
''%%http://example.com/api/v1/%%upload_avatar''
^ NAME ^ DESCRIPTION ^ Type ^
| avatar | Accepted avatar dimension is 128px*128px if dimensions are higher the image will be cropped | file |
====jQuery Example====
var form = new FormData();
form.append("avatar", "Sasa.png");
var settings = {
"async": true,
"crossDomain": true,
"url": "http://example.com/api/v1/upload_avatar",
"method": "POST",
"headers": {
"access-code": "YOUR_ACCESS_CODE"
},
"processData": false,
"contentType": false,
"mimeType": "multipart/form-data",
"data": form
}
$.ajax(settings).done(function (response) {
console.log(response);
});
====On Success Response ====
{
"success": "http://example.com/assets/uploads/avatar/6bb8aae67ff8.png"
}
====On Error Response====
{
"error": "The filetype you are attempting to upload is not allowed.",
"code": 1031
}
===== Update User =====
Calling update_user method is POST action & must be [[:api:main#authentication|Authenticated]].
This method will allow you to update User full name, email and password.
**URL Example**
''%%http://example.com/api/v1/%%update_user''
Changing user email or password will immediately revoked your current ACCESS-CODE.
In this method response you will receive new ACCESS-CODE which you need to override with what you using or otherwise the next action method you call you will get error 1051 which will required you to [[api:main#login_retrieve_accesscode|relogin and retrieve ACCESS-CODE]].
**Parameters**
^ NAME ^ DESCRIPTION ^ Type ^
| full_name | User new full name | String |
| identity | User new email address | String |
| password | User new password | String |
This command response is use exactly same output as in [[api:main&#auth_response|Auth Response]], make sure to save the new accessCode output to your database for the future use.
===== Un-Register Device =====
Calling unregister_device method is GET action & must be [[:api:main#authentication|Authenticated]].
This method will allow you to remove/un-register Device from Push Notification, required in Logout.
**URL Example**
''%%http://example.com/api/v1/%%unregister_device?objectId=UrStoredParseObjectId''
**Parameters**
^ NAME ^ DESCRIPTION ^ Type ^
| objectId | Stored Parse.com Object ID | String |
** cURL Example **
curl -X GET -H "access-code: YourAccessCode" -H "Cache-Control: no-cache" -H 'http://example.com/api/v1/unregister_device?objectId=UrStoredParseObjectId'
** Response **
{
"success":"Device been successfully removed."
}
===== Errors & HTTP Codes =====
The following HTTP Status description to guide you which we do currently used.
for official HTTP Status codes visit [[http://www.ietf.org/assignments/http-status-codes/http-status-codes.xml|ietef.org]]
^ CODE ^ DESCRIPTION ^
| 200 | Accepted Request |
| 401 | Login Incorrect or API access code may be revoked or doesn't match current user password |
| 403 | Forbidden method due to user/group restrictions |
| 404 | Calling unknown method |
==== Registered Errors ====
^ CODE ^ HTTP STATUS ^ MESSAGE ^
| 1001 | 404 | Missing Parameters ! |
| 1002 | 401 | We'll be back soon! Server currently under maintenance. |
| 1020 | 404 | Missing GroupID Parameter ! |
| 1030 | 404 | Form Validation error, return in Array |
| 1031 | 404 | Validation error on uploading |
| 1032 | 404 | Attachment File may not exist ! |
| 1050 | 401 | Invalid Identity or/and Password |
| 1051 | 401 | Invalid accessCode |
| 1052 | 401 | User is Disabled |
| 1053 | 403 | Forbidden action for this user group ! |
| 1054 | 403 | Forbidden action for this user ! |
| 1055 | 403 | This Student has not created user account ! |
| 1056 | 401 | User is Suspended |
| 1060 | 404 | This contact is may already deleted or invalid ID |
| 1061 | 400 | Duplicated Email Address |
| 1062 | 400 | The selected language is not exist! |
| 1070 | 404 | Sorry, You cannot reply to this Message ! |
| 1071 | 403 | Cannot delete your private message, this can be due to your school disabled the deletion of the messages |
| 1080 | 404 | You Entered incorrect school code ! |
| 1081 | 500 | Application outdated, Update Required ! |
| 1090 | 404 | Invalid Notification, cannot be open ! |