JSON API

Jeremy edited this page Mar 7, 2018 · 31 revisions

This is the API Reference.

Data is to be accessed through HTTP Requests to https://vitacademics-rel.herokuapp.com/
All data is received as JSON.

Usage

All requests to the API are HTTP POST Requests unless specified.

System API

This is a HTTP GET Request.

$ curl https://vitacademics-rel.herokuapp.com/api/v2/system
Logging In

The user has to first to login through the following Request:

$ curl --data "regno=<reg-number>&dob=<dob>&mobile=<mobile>" https://vitacademics-rel.herokuapp.com/api/v2/<campus>/login

where:

  • reg-number is to be replaced with your registration number (case insensitive)

  • dob is to be replaced with your date of birth (eg. 12051994)

  • mobile is to be replaced with your Parent's mobile number that is registered with VIT (eg: 9876543210)

  • campus can have the values (case sensitive):

    • vellore
    • chennai
Fetching/Refreshing Data

The data can be fetched (for the first time) or refreshed by the usage of the following request:

$ curl --data "regno=<reg-number>&dob=<dob>&mobile=<mobile>" https://vitacademics-rel.herokuapp.com/api/v2/<campus>/refresh

where the values for reg-number, dob, campus are the same as above.

Token

The token to share the timetable with a friend can be obtained by the following:

$ curl --data "regno=<reg-number>&dob=<dob>&mobile=<mobile>" https://vitacademics-rel.herokuapp.com/api/v2/<campus>/token
Share

The token obtained from above can be used to share timetable data who's credentials were used above to generate the token:

$ curl --data "token=<token>&receiver=<receiver-reg-number>" https://vitacademics-rel.herokuapp.com/api/v2/<campus>/share

Sharing can be done directly through:

$ curl --data "regno=<reg-number>&dob=<dob>&mobile=<mobile>&receiver=<receiver-reg-number>" https://vitacademics-rel.herokuapp.com/api/v2/<campus>/share

This returns the timetable of the person who's credentials were given.

Grades

The academic history and grades can be obtained by the following:

$ curl --data "regno=<reg-number>&dob=<dob>&mobile=<mobile>" https://vitacademics-rel.herokuapp.com/api/v2/<campus>/grades
Faculty Advisor Information

The faculty advisor information can be obtained by the following:

$ curl --data "regno=<reg-number>&dob=<dob>&mobile=<mobile>" https://vitacademics-rel.herokuapp.com/api/v2/<campus>/advisor
Spotlight

This is a HTTP GET Request.

$ curl https://vitacademics-rel.herokuapp.com/api/v2/<campus>/spotlight
Faculty Information

The information regarding any faculty (Vellore Campus currently) can be obtained by the following:

$ curl https://vitacademics-rel.herokuapp.com/api/v2/vellore/faculty --data "name=<name-of-faculty-as-sent-in-course-details>"

Return Values

A successful login returns a JSON object like the following:

{"reg_no":"<reg-number>","dob":"<dob>","mobile":"<mobile>","campus":"<campus>","name":"<name>","status":{"message":"Successful Execution","code":0}}

A successful refresh would return a JSON having the Course Data, Attendance, Marks for the user in the format:

{
    reg_no:<reg-no>,
    dob: <dob>,
    mobile: <mobile>,
    campus: <campus>,
    courses: [{ all courses in a list with all details (faculty name, timings, attendance, marks}],
    semster: <semester-type>,
    refreshed: <timestamp>
    withdrawn_courses: []
}

A successful token generation would return the token in a JSON:

{"reg_no":<reg-number>, "dob":<dob>, "mobile":"<mobile>", "campus":<campus>, "share":{"token":"ABC123","validity":24,"issued":"<timestamp>"},"status":{"message":"Successful Execution","code":0}}

A share request returns the timetable in JSON.

A grades request returns the academic history in the following format:

{
   reg_no: <reg-no>,
   dob: <dob>,
   mobile: <mobile>,
   campus: <campus>,
   grades: [ List of All Courses:
                {
                    course_code:
                    course_title:
                    course_type:
                    credits:
                    grade:
                    exam_held:
                    result_date:
                    option:
                }
            ]
    semester_wise: { List of Semesters - "examYear-examMonth" : { credits: , gpa: }}
    credits_registered: 
    credits_earned:
    cgpa:
    grade_summary: {"gradeValue": Number of Times Scored }
    grades_refreshed:
    cached:
    status:
}

A successful fetch for Advisor Information would return the following JSON:

{
     "reg_no": <reg-no>,
     "dob": <dob>,
     "mobile": <mobile>,
     "campus": <campus>,
     "advisor": {
                    "name": string
                    "designation": string
                    "school": string
                    "division": string
                    "phone": string
                    "email": string
                    "cabin": string
                    "intercom": string
                },
     "status":{}
}

A successful fetch for the spotlight returns data in the following JSON format:

{
     "campus": <campus>,
     "spotlight": {
                    "academics": [{"text": string, "url": string}],
                    "coe": [{"text": string, "url": string}],
                    "research": [{"text": string, "url": string}]
                },
     "status":{}
}

A successful request for faculty information returns data in the following JSON format:

{
     "name": string
     "room": string
     "open_hours": [{day: , start_time: , end_time: }]
     "email": string
     "school": string
     "status":{}
}

A system request returns the details regarding the latest and supported versions of the Client Apps on iOS, Android and Windows Platforms in the following format:

{
    "platform" : {"latest": , "supported": }
    "messages": []
    "status": {}
}

Any erroneous response can be checked using the status code returned:

  • 0: Success
  • 11: Session Timed Out
  • 12: Invalid Credentials
  • 13: Error Parsing the Captcha
  • 14: Token Expired
  • 15: Requested Data Unavailable
  • 16: Error Parsing Data / Invalid Credentials
  • 50: Feature Incomplete
  • 60: Feature or Endpoint Deprecated
  • 89: VIT servers are down / Connectivity Issue
  • 97: MongoLab Issue / Connectivity Issue
  • 98: Down for Maintenance
  • 99: Unforeseen Error

Key Legends:

Course Type is present in a key called "course_type". It has the following values:

  • CBL Course: 1
  • LBC Course: 2
  • PBL Course: 3
  • RBL Course: 4
  • PBC Course with specific information (like Project Title, Guide (which is "faculty")): 5
  • PBC Course with no such information: 6
  • Unsupported Course Type: 0 (Something new that VIT has introduced)

Any issues, bugs or features you would like to be added can be reported here.

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.