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 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 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 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 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 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 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 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 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
1070 404 Sorry, You cannot reply to this Message !
1080 404 You Entered incorrect school code !
1081 500 Application outdated, Update Required !