Madrasa API API Reference

The Api powering the Madrasa website

API Endpoint
https://api.madrasa.org/
Contact: [email protected]
Request Content-Types: application/json
Response Content-Types: application/json
Schemes: https
Version: 1.0.0

Authentication

jwt_token

Authentication token got during the login. Header syntax: Authorization: Bearer <json_web_token>

type
basic
name
Authorization
in
header

Reset Password

Reset Password

GET /check-reset-password-token

Checks if a reset password token is valid

Example /check-reset-password-token?<token>

token: string
in query

The token to check the validity

200 OK

The token is valid. The endpoint also returns the email of the user associated with the reset token.

type
object
422 Unprocessable Entity

The token is invalid / expired or unknown

type
object
Response Content-Types: application/json
Response Example (200 OK) 
{
  "status": "valid",
  "email": "[email protected]"
}
Response Example (422 Unprocessable Entity) 
{
  "message": "invalid_token"
}
Reset Password

POST /send-reset-password-email

sends a reset password email

email: string
in post

The email to send the reset password

lang: string
in post

The language of the email which will be sent, 'ar' or 'en', default is arabic ('ar')

200 OK

Success on sending the reset email

type
object
404 Not Found

Unknown email, the email provided does not exist in the database.

type
object
422 Unprocessable Entity

The user has been registred through a social login and does not have a password to reset.

type
object
Response Content-Types: application/json
Response Example (200 OK) 
{
  "message": "ok"
}
Response Example (404 Not Found) 
{
  "message": "unkwown_user"
}
Response Example (422 Unprocessable Entity) 
{
  "message": "use_facebook_auth"
}
Reset Password

POST /reset-password

Login

Login

POST /login

Login with a wordpress account The JSON token you get back can be then used in the HTML headers: Authorization : Bearer <json_web_token>

email: string
in post

email of the user

password: string
in query

password

200 OK
AccessToken

JSON access token

500 Internal Server Error
Error

unexpected error

Response Content-Types: application/json
Response Example (200 OK) 
{
  "accessToken": "<json_web_token>"
}
Response Example (500 Internal Server Error) 
{
  "message": "string"
}
Login

GET /login/facebook

Login redirection to Facebook

301 Moved Permanently

Redirects directly the user to the Facebook auth page

It will redirect then back to {website URL}/login/social/callback with the following in the url parameters:

  • Sent all the time: type=facebook (type will be google for the google auth)
  • Sent on success only: accessToken=<JWT TOKEN>, you will receive the accessToken used for this user.
  • Sent on failure only: error=<error string>, on error you will receive an error in the query string, this error can either be social_auth_needs_email if the user denied access to the email address on the Facebook modal (email is mandatory) or any error string returned by Facebook.
Response Content-Types: application/json
Login

GET /login/google

Login redirection to Google

301 Moved Permanently

Redirects directly the user to the Google auth page

It will redirect then back to {website URL}/login/social/callback with the following in the url parameters:

  • Sent all the time: type=google (type will be Facebook for the Facebook auth)
  • Sent on success only: accessToken=<JWT TOKEN>, you will receive the accessToken used for this user.
  • Sent on failure only: error=<error string>, on error you will receive an error in the query string, this error can either be social_auth_needs_email if the user denied access to the email address on the Google modal (email is mandatory) or any error string returned by Google.
Response Content-Types: application/json
Login

GET /register/facebook/callback

Login throuh Facebook with a Facebook token, it should only be used by mobile apps

Example: /register/facebook/callback?code=<facebook-access-token>&get-token

code: string
in query

Facebook auth token returned by the Facebook SDK

get-token: string
in query

Asks the API to return the token directly instead of redirecting (strongly recommended for mobile apps)

200 OK
AccessToken

App access token to use for any authenticated call

500 Internal Server Error
Error

Facebook authentication failed

Response Content-Types: application/json
Response Example (200 OK) 
{
  "accessToken": "<json_web_token>"
}
Response Example (500 Internal Server Error) 
{
  "message": "string"
}
Login

GET /register/google/mobile

Login throuh Google with a Google token, it should only be used by mobile apps

Example: /register/google/mobile?code=<google-code>&scope=openid+email+https://www.googleapis.com/auth/plus.me+https://www.googleapis.com/auth/userinfo.email&get-token

code: string
in query

Google auth token returned by the Google SDK

scope: string
in query

Google API data scope

Example: openid+email+https://www.googleapis.com/auth/plus.me+https://www.googleapis.com/auth/userinfo.email

get-token: string
in query

Asks the API to return the token directly instead of redirecting (strongly recommended for mobile apps)

200 OK
AccessToken

App access token to use for any authenticated call

500 Internal Server Error
Error

Google authentication failed

Response Content-Types: application/json
Response Example (200 OK) 
{
  "accessToken": "<json_web_token>"
}
Response Example (500 Internal Server Error) 
{
  "message": "string"
}

Profile

Profile

GET /profile

returns the user profile

200 OK
Profile

user profile

Response Content-Types: application/json
Response Example (200 OK) 
{
  "id": "6f3d0648-37eb-4d5a-b7a0-86e63a1bdc53",
  "first_name": "John",
  "last_name": "Doe",
  "date_of_birth": "1991-07-30",
  "gender": "female",
  "city": "Nancy",
  "type": "student",
  "updated_at": "2018-12-03T09:04:42.000Z",
  "nationality_": {
    "id": "f30d83b1-69d9-4edd-94a7-9c5003cd0942",
    "code": "TD",
    "name_en": "Chad",
    "name_ar": "تشاد"
  },
  "country_of_residence_": {
    "id": "f30d83b1-69d9-4edd-94a7-9c5003cd0942",
    "code": "TD",
    "name_en": "Chad",
    "name_ar": "تشاد"
  }
}

Category

Category

GET /category

Get all the categories

with: string sections, sub_sections
in query

Get associated data.

  • If you use /category/with:sections, you will get an arrary of sections for each category
  • If you use /category/with:sub_sections, you will get sections with sub_sections inside for each category.
200 OK
Category

List of all the categories

type
Category
Response Content-Types: application/json
Response Example (200 OK) 
[
  {
    "id": "f30d83b1-69d9-4edd-94a7-9c5003cd0942",
    "title": "الرياضيات",
    "icon_url": "https://madrasa.org/wp-content/themes/education_v2/imgs/vidLib/15.png",
    "slug": "الرياضيات",
    "created_at": "2018-12-03T09:04:42.000Z",
    "updated_at": "2018-12-03T09:04:42.000Z",
    "enabled": true,
    "weight": 0,
    "tags": [
      "toto"
    ]
  }
]
Category

GET /category/{categoryId}

Get a category

categoryId: string (uuid)
in path

Sections associated with a category id

with: string sections, sub_sections
in query

Get associated data.

  • If you use /category/{categoryId}/with:sections, you will get an array of sections for the category
  • If you use /category/{categoryId}/with:sub_sections, you will get sections with sub_sections inside for the category.
200 OK
Category

Get the category from its ID

422 Unprocessable Entity
InvalidUuid

Invalid id provided

Response Content-Types: application/json
Response Example (200 OK) 
{
  "id": "f30d83b1-69d9-4edd-94a7-9c5003cd0942",
  "title": "الرياضيات",
  "icon_url": "https://madrasa.org/wp-content/themes/education_v2/imgs/vidLib/15.png",
  "slug": "الرياضيات",
  "created_at": "2018-12-03T09:04:42.000Z",
  "updated_at": "2018-12-03T09:04:42.000Z",
  "enabled": true,
  "weight": 0,
  "tags": [
    "toto"
  ]
}
Response Example (422 Unprocessable Entity)
Category

GET /category/slug/{categorySlug}

Get a category by slug

categorySlug: string (uuid)
in path

The slug of the category

with: string sections, sub_sections
in query

Get associated data.

  • If you use /category/{categoryId}/with:sections, you will get an array of sections for the category
  • If you use /category/{categoryId}/with:sub_sections, you will get sections with sub_sections inside for the category.
200 OK
Category

Get a category according from its slug

422 Unprocessable Entity
InvalidUuid

Invalid id provided

Response Content-Types: application/json
Response Example (200 OK) 
{
  "id": "f30d83b1-69d9-4edd-94a7-9c5003cd0942",
  "title": "الرياضيات",
  "icon_url": "https://madrasa.org/wp-content/themes/education_v2/imgs/vidLib/15.png",
  "slug": "الرياضيات",
  "created_at": "2018-12-03T09:04:42.000Z",
  "updated_at": "2018-12-03T09:04:42.000Z",
  "enabled": true,
  "weight": 0,
  "tags": [
    "toto"
  ]
}
Response Example (422 Unprocessable Entity)
Category Sections & Subsections

GET /category/{categoryId}/sections

Get sections by category

categoryId: string (uuid)
in path

Sections associated with a category id

200 OK
Section

Get the sections associated with the category

type
Section
422 Unprocessable Entity
InvalidUuid

Invalid id provided

Response Content-Types: application/json
Response Example (200 OK) 
[
  {
    "id": "5cf46551-b699-44ca-94c5-025e86685e32",
    "title": "العد",
    "icon_url": "https://madrasa.org/wp-content/themes/education_v2/imgs/vidLib/15.png",
    "slug": "العد",
    "created_at": "2018-12-03T09:05:50.000Z",
    "updated_at": "2018-12-03T09:05:50.000Z",
    "enabled": false,
    "weight": 0,
    "tags": [
      "العد"
    ],
    "category_id": "f30d83b1-69d9-4edd-94a7-9c5003cd0942"
  }
]
Response Example (422 Unprocessable Entity)

Likes

Likes

GET /user/like

Get the whole list of user likes (only likes on lessons are supported for now)

Authorization: string
in headers

Authentication token got during the login. Header syntax: Authorization: Bearer <json_web_token>

200 OK

undefined

type
object
Response Content-Types: application/json
Response Example (200 OK) 
{
  "lessons": [
    "289f7211-3a94-4cc5-b282-997fb38e8651"
  ]
}
jwt_token
Likes

GET /like/{lessonId}

Like or unlike a lesson

Authorization: string
in headers

Authentication token got during the login. Header syntax: Authorization: Bearer <json_web_token>

lessonId: object
in query

Id of the lesson to like or unlike

200 OK

undefined

type
object
Response Content-Types: application/json
Response Example (200 OK) 
{
  "message": "ok",
  "like": true
}
jwt_token

Competition

Competition

GET /winner

Get a list of the last 7 winners of the competition

Authorization: string
in headers

Authentication token got during the login. Header syntax: Authorization: Bearer <json_web_token>

200 OK

the list of the last 7 winners ordered by most recent winning date.

type
object[]
Response Content-Types: application/json
Response Example (200 OK) 
[
  {
    "id": "0f6c6cd4-3379-45be-a28a-d05d2ae010ba",
    "created_at": "2018-12-03T09:04:42.000Z",
    "selection_status": "winner",
    "reviewed_date": "2018-12-03T09:04:42.000Z",
    "profile": {
      "id": "6f3d0648-37eb-4d5a-b7a0-86e63a1bdc53",
      "first_name": "John",
      "last_name": "Doe",
      "date_of_birth": "1991-07-30",
      "gender": "female",
      "city": "Nancy",
      "type": "student",
      "updated_at": "2018-12-03T09:04:42.000Z",
      "nationality_": {
        "id": "f30d83b1-69d9-4edd-94a7-9c5003cd0942",
        "code": "TD",
        "name_en": "Chad",
        "name_ar": "تشاد"
      },
      "country_of_residence_": {
        "id": "f30d83b1-69d9-4edd-94a7-9c5003cd0942",
        "code": "TD",
        "name_en": "Chad",
        "name_ar": "تشاد"
      }
    }
  }
]
jwt_token
Competition

POST /question/answer

answers the current question for the competition, you might get events back with points.

Authorization: string
in headers

Authentication token got during the login. Header syntax: Authorization: Bearer <json_web_token>

answerId: string
in post

The answer id

example: answerId=d19fbe0a-bd03-4fdc-9adb-2c99f6999215

200 OK

The current question of the day for the competition, you might get events back with points

type
object
422 Unprocessable Entity

Missing argument

type
object
Response Content-Types: application/json
Response Example (200 OK) 
{
  "message": "ok",
  "events": {
    "points": 5
  }
}
Response Example (422 Unprocessable Entity) 
{
  "message": "missing_argument",
  "argument": "answerId"
}
jwt_token
Competition

GET /question/current

Gets the current question of the day for the competition

200 OK
Question

The current question of the day for the competition

Response Content-Types: application/json
Response Example (200 OK) 
{
  "id": "f30d83b1-69d9-4edd-94a7-9c5003cd0942",
  "created_at": "2019-01-22T05:07:01.079Z",
  "order": 1,
  "status": "current",
  "type": "text",
  "value": "اشترى سمير تفاحًا وموزًا من البقالّة. إذا علمت أنّ ثمن التفاح 25.85 درهمًا والموز 20.655 درهمًا، وأنّ قيمة الضريبة المضافة عليهما معًا تبلغ 2.3 درهمًا، كم يجب أن يدفع سمير لصاحب البقالة؟",
  "begin_at": "2019-01-22T00:00:00.000Z",
  "end_at": "2019-01-23T00:00:00.000Z",
  "answer_type": "mcq",
  "answers": [
    {
      "id": "d19fbe0a-bd03-4fdc-9adb-2c99f6999215",
      "created_at": "2019-01-22T05:07:01.092Z",
      "value": "hello"
    }
  ],
  "lessson_": {
    "id": "6f3d0648-37eb-4d5a-b7a0-86e63a1bdc53",
    "title": "عدّ الأرقام الصغيرة",
    "icon_url": "https://madrasa.org/wp-content/themes/education_v2/imgs/vidLib/15.png",
    "slug": "عدّ الأرقام الصغيرة",
    "created_at": "2018-12-03T09:05:50.000Z",
    "updated_at": "2018-12-03T09:05:50.000Z",
    "enabled": false,
    "weight": 1,
    "tags": [
      "عدّ الأرقام الصغيرة"
    ],
    "youtube_video_id": "2345678901",
    "description": "عدّ الأرقام الصغيرة",
    "sub_section_id": "0f6c6cd4-3379-45be-a28a-d05d2ae010ba"
  }
}

Lesson

Gamification Lesson

GET /daily/lesson

returns the daily lesson

200 OK
Lesson

The daily lesson

Response Content-Types: application/json
Response Example (200 OK) 
{
  "id": "6f3d0648-37eb-4d5a-b7a0-86e63a1bdc53",
  "title": "عدّ الأرقام الصغيرة",
  "icon_url": "https://madrasa.org/wp-content/themes/education_v2/imgs/vidLib/15.png",
  "slug": "عدّ الأرقام الصغيرة",
  "created_at": "2018-12-03T09:05:50.000Z",
  "updated_at": "2018-12-03T09:05:50.000Z",
  "enabled": false,
  "weight": 1,
  "tags": [
    "عدّ الأرقام الصغيرة"
  ],
  "youtube_video_id": "2345678901",
  "description": "عدّ الأرقام الصغيرة",
  "sub_section_id": "0f6c6cd4-3379-45be-a28a-d05d2ae010ba"
}
Lesson

GET /video-activity

returns an array of the last 5 lesson watched. Returns the data from POST /lesson/{lessonId}/record-video-activity (see documentation of this endpoint)

200 OK
VideoActivity

returns an array of the last 5 lesson watched. Returns the data from POST /lesson/{lessonId}/record-video-activity (see documentation of this endpoint)

type
VideoActivity
Response Content-Types: application/json
Response Example (200 OK) 
[
  {
    "id": "5cf46551-b699-44ca-94c5-025e86685e32",
    "type": "completed",
    "lesson_": {
      "id": "6f3d0648-37eb-4d5a-b7a0-86e63a1bdc53",
      "title": "عدّ الأرقام الصغيرة",
      "icon_url": "https://madrasa.org/wp-content/themes/education_v2/imgs/vidLib/15.png",
      "slug": "عدّ الأرقام الصغيرة",
      "created_at": "2018-12-03T09:05:50.000Z",
      "updated_at": "2018-12-03T09:05:50.000Z",
      "enabled": false,
      "weight": 1,
      "tags": [
        "عدّ الأرقام الصغيرة"
      ],
      "youtube_video_id": "2345678901",
      "description": "عدّ الأرقام الصغيرة",
      "sub_section_id": "0f6c6cd4-3379-45be-a28a-d05d2ae010ba"
    }
  }
]
jwt_token
Watchlist Lesson

POST /watchlist/{lessonId}

Add a lesson to the watchlist

200 OK

Add a lesson successfully

type
object
422 Unprocessable Entity

The lesson id does not exist

type
object
Response Content-Types: application/json
Response Example (200 OK) 
{
  "message": "ok"
}
Response Example (422 Unprocessable Entity) 
{
  "message": "entity_not_found"
}
jwt_token
Watchlist Lesson

DELETE /watchlist/{lessonId}

Deletes a lesson from the watchlist

200 OK

Add a lesson successfully

type
object
Response Content-Types: application/json
Response Example (200 OK) 
{
  "message": "ok"
}
jwt_token
Lesson

POST /lesson/{lessonId}/record-video-activity

Records the activity of the user when watching a video

Authorization: string
in headers

Authentication token got during the login. Header syntax: Authorization: Bearer <json_web_token>

event: string
in post

The event can only be 'started' or 'completed', the api will refuse anything else.

200 OK

The event has been recorded, if you send a completed event, you get one point back as an event.

type
object
422 Unprocessable Entity

The event is invalid

type
object
Response Example (200 OK) 
{
  "message": "ok",
  "events": {
    "points": 1
  }
}
Response Example (422 Unprocessable Entity) 
{
  "message": "invalid_event",
  "text": "event must be either \"started\" or \"completed\""
}
Lesson

GET /lesson/{lessonId}

Get lesson by Id

lessonId: string (uuid)
in path

Get a lesson by id

200 OK
Lesson

Get a lesson by id

404 Not Found

Lesson not found

type
object
422 Unprocessable Entity
InvalidUuid

Invalid id provided

Response Content-Types: application/json
Response Example (200 OK) 
{
  "id": "6f3d0648-37eb-4d5a-b7a0-86e63a1bdc53",
  "title": "عدّ الأرقام الصغيرة",
  "icon_url": "https://madrasa.org/wp-content/themes/education_v2/imgs/vidLib/15.png",
  "slug": "عدّ الأرقام الصغيرة",
  "created_at": "2018-12-03T09:05:50.000Z",
  "updated_at": "2018-12-03T09:05:50.000Z",
  "enabled": false,
  "weight": 1,
  "tags": [
    "عدّ الأرقام الصغيرة"
  ],
  "youtube_video_id": "2345678901",
  "description": "عدّ الأرقام الصغيرة",
  "sub_section_id": "0f6c6cd4-3379-45be-a28a-d05d2ae010ba"
}
Response Example (404 Not Found) 
{
  "message": "lesson not found"
}
Response Example (422 Unprocessable Entity)
Lesson

GET /lesson/slug/{lessonSlug}

Get lesson by Slug

lessonSlug: string (uuid)
in path

Get a lesson by id

200 OK
Lesson

Get a lesson by id

404 Not Found

Lesson not found

type
object
422 Unprocessable Entity
InvalidUuid

Invalid id provided

Response Content-Types: application/json
Response Example (200 OK) 
{
  "id": "6f3d0648-37eb-4d5a-b7a0-86e63a1bdc53",
  "title": "عدّ الأرقام الصغيرة",
  "icon_url": "https://madrasa.org/wp-content/themes/education_v2/imgs/vidLib/15.png",
  "slug": "عدّ الأرقام الصغيرة",
  "created_at": "2018-12-03T09:05:50.000Z",
  "updated_at": "2018-12-03T09:05:50.000Z",
  "enabled": false,
  "weight": 1,
  "tags": [
    "عدّ الأرقام الصغيرة"
  ],
  "youtube_video_id": "2345678901",
  "description": "عدّ الأرقام الصغيرة",
  "sub_section_id": "0f6c6cd4-3379-45be-a28a-d05d2ae010ba"
}
Response Example (404 Not Found) 
{
  "message": "lesson not found"
}
Response Example (422 Unprocessable Entity)

Sections & Subsections

Category Sections & Subsections

GET /category/{categoryId}/sections

Get sections by category

categoryId: string (uuid)
in path

Sections associated with a category id

200 OK
Section

Get the sections associated with the category

type
Section
422 Unprocessable Entity
InvalidUuid

Invalid id provided

Response Content-Types: application/json
Response Example (200 OK) 
[
  {
    "id": "5cf46551-b699-44ca-94c5-025e86685e32",
    "title": "العد",
    "icon_url": "https://madrasa.org/wp-content/themes/education_v2/imgs/vidLib/15.png",
    "slug": "العد",
    "created_at": "2018-12-03T09:05:50.000Z",
    "updated_at": "2018-12-03T09:05:50.000Z",
    "enabled": false,
    "weight": 0,
    "tags": [
      "العد"
    ],
    "category_id": "f30d83b1-69d9-4edd-94a7-9c5003cd0942"
  }
]
Response Example (422 Unprocessable Entity)
Sections & Subsections

GET /section/{sectionId}

Get a section by Id

sectionId: string (uuid)
in path

Get a section by id

with: string sub_sections, lessons
in query

Get associated data.

  • If you use /section/{sectionId}/with:sub_sections, you will get an array of sub_section for the section
  • If you use /section/{sectionId}/with:lessons, you will get sub_section with lessons inside for the section.
200 OK
Section

Get a section by id

404 Not Found

Entity not found

type
object
422 Unprocessable Entity
InvalidUuid

Invalid id provided

Response Content-Types: application/json
Response Example (200 OK) 
{
  "id": "5cf46551-b699-44ca-94c5-025e86685e32",
  "title": "العد",
  "icon_url": "https://madrasa.org/wp-content/themes/education_v2/imgs/vidLib/15.png",
  "slug": "العد",
  "created_at": "2018-12-03T09:05:50.000Z",
  "updated_at": "2018-12-03T09:05:50.000Z",
  "enabled": false,
  "weight": 0,
  "tags": [
    "العد"
  ],
  "category_id": "f30d83b1-69d9-4edd-94a7-9c5003cd0942"
}
Response Example (404 Not Found) 
{
  "message": "Entity not found"
}
Response Example (422 Unprocessable Entity)
Sections & Subsections

GET /section/slug/{sectionSlug}

Get a section by slug

sectionSlug: string (uuid)
in path

Get a section by slug

with: string sub_sections, lessons
in query

Get associated data.

  • If you use /section/{sectionId}/with:sub_sections, you will get an array of sub_section for the section
  • If you use /section/{sectionId}/with:lessons, you will get sub_section with lessons inside for the section.
200 OK
Section

Get a section by slug

404 Not Found

Entity not found

type
object
Response Content-Types: application/json
Response Example (200 OK) 
{
  "id": "5cf46551-b699-44ca-94c5-025e86685e32",
  "title": "العد",
  "icon_url": "https://madrasa.org/wp-content/themes/education_v2/imgs/vidLib/15.png",
  "slug": "العد",
  "created_at": "2018-12-03T09:05:50.000Z",
  "updated_at": "2018-12-03T09:05:50.000Z",
  "enabled": false,
  "weight": 0,
  "tags": [
    "العد"
  ],
  "category_id": "f30d83b1-69d9-4edd-94a7-9c5003cd0942"
}
Response Example (404 Not Found) 
{
  "message": "Entity not found"
}
Sections & Subsections

GET /subsection/{subsectionId}

Get a subsection by id

subsectionId: string (uuid)
in path

Get a subsection by Id

with: string lessons
in query

Get associated data.

  • If you use /subsection/{subsectionId}/with:lessons, you will get an array of lessons inside the subsection object.
200 OK
Subsection

Get a subsection by id

404 Not Found

Entity not found

type
object
422 Unprocessable Entity
InvalidUuid

Invalid id provided

Response Content-Types: application/json
Response Example (200 OK) 
{
  "id": "0f6c6cd4-3379-45be-a28a-d05d2ae010ba",
  "title": "الأعداد من 0 إلى 120",
  "title_en": "English Title",
  "icon_url": "https://madrasa.org/wp-content/themes/education_v2/imgs/vidLib/15.png",
  "slug": "الأعداد من 0 إلى 120",
  "created_at": "2018-12-03T09:04:42.000Z",
  "updated_at": "2018-12-03T09:04:42.000Z",
  "weight": 0,
  "enabled": true,
  "youtube_playlist_id": "1234567890"
}
Response Example (404 Not Found) 
{
  "message": "Entity not found"
}
Response Example (422 Unprocessable Entity)
Sections & Subsections

GET /subsection/slug/{subsectionSlug}

Get a subsection by slug

Examples for slug الأعداد من 0 إلى 120:

  • /subsection/slug/%D8%A7%D9%84%D8%A3%D8%B9%D8%AF%D8%A7%D8%AF+%D9%85%D9%86+0+%D8%A5%D9%84%D9%89+120
  • /subsection/slug/%D8%A7%D9%84%D8%A3%D8%B9%D8%AF%D8%A7%D8%AF+%D9%85%D9%86+0+%D8%A5%D9%84%D9%89+120/with:lessons
sectionSlug: string (uuid)
in path

Get a section by slug

with: string lessons
in query

Get associated data.

  • If you use /subsection/slug/{subsectionSlug}/with:lessons, you will get an array of lessons inside the subsection object.
200 OK
Subsection

Get a subsection by slug

404 Not Found

Entity not found

type
object
422 Unprocessable Entity
InvalidUuid

Invalid id provided

Response Content-Types: application/json
Response Example (200 OK) 
{
  "id": "0f6c6cd4-3379-45be-a28a-d05d2ae010ba",
  "title": "الأعداد من 0 إلى 120",
  "title_en": "English Title",
  "icon_url": "https://madrasa.org/wp-content/themes/education_v2/imgs/vidLib/15.png",
  "slug": "الأعداد من 0 إلى 120",
  "created_at": "2018-12-03T09:04:42.000Z",
  "updated_at": "2018-12-03T09:04:42.000Z",
  "weight": 0,
  "enabled": true,
  "youtube_playlist_id": "1234567890"
}
Response Example (404 Not Found) 
{
  "message": "not_found"
}
Response Example (422 Unprocessable Entity)

Watchlist

Watchlist

GET /watchlist

returns an array of all the lessons to watch later. The watchlist is like a bookmark feature for lessons.

200 OK
Watchlist

undefined

type
Watchlist
Response Content-Types: application/json
Response Example (200 OK) 
[
  {
    "id": "f30d83b1-69d9-4edd-94a7-9c5003cd0942",
    "created_at": "2019-01-22T05:07:01.079Z",
    "lesson_": {
      "id": "6f3d0648-37eb-4d5a-b7a0-86e63a1bdc53",
      "title": "عدّ الأرقام الصغيرة",
      "icon_url": "https://madrasa.org/wp-content/themes/education_v2/imgs/vidLib/15.png",
      "slug": "عدّ الأرقام الصغيرة",
      "created_at": "2018-12-03T09:05:50.000Z",
      "updated_at": "2018-12-03T09:05:50.000Z",
      "enabled": false,
      "weight": 1,
      "tags": [
        "عدّ الأرقام الصغيرة"
      ],
      "youtube_video_id": "2345678901",
      "description": "عدّ الأرقام الصغيرة",
      "sub_section_id": "0f6c6cd4-3379-45be-a28a-d05d2ae010ba"
    }
  }
]
jwt_token
Watchlist Lesson

POST /watchlist/{lessonId}

Add a lesson to the watchlist

200 OK

Add a lesson successfully

type
object
422 Unprocessable Entity

The lesson id does not exist

type
object
Response Content-Types: application/json
Response Example (200 OK) 
{
  "message": "ok"
}
Response Example (422 Unprocessable Entity) 
{
  "message": "entity_not_found"
}
jwt_token
Watchlist Lesson

DELETE /watchlist/{lessonId}

Deletes a lesson from the watchlist

200 OK

Add a lesson successfully

type
object
Response Content-Types: application/json
Response Example (200 OK) 
{
  "message": "ok"
}
jwt_token

Gamification

Gamification

GET /leaderboard/global

Returns the 100 best players by number of points. Sorted by best player first

200 OK

Returns the 100 best players by number of points. Sorted by best player first

type
object[]
Response Content-Types: application/json
Response Example (200 OK) 
[
  {
    "points": 15,
    "first_name": "John",
    "last_name": "Doe",
    "nickname": "TheGreatPlayer42",
    "grade": {
      "id": "64c80d38-e50f-4f39-a089-7bb613223ffc",
      "name_en": "Beginner",
      "name_ar": "مبتدئ",
      "points": 10
    }
  }
]
Gamification

GET /leaderboard/by-country

Returns the best players per country, also returns the countries without any players

200 OK

Returns the best players per country, also returns the countries without any players

type
object[]
Response Content-Types: application/json
Response Example (200 OK) 
[
  {
    "id": "d162b927-912e-490d-bae6-e14dab16abf3",
    "country_": {
      "id": "f30d83b1-69d9-4edd-94a7-9c5003cd0942",
      "code": "TD",
      "name_en": "Chad",
      "name_ar": "تشاد"
    },
    "users": [
      {
        "id": "d162b927-912e-490d-bae6-e14dab16abf3",
        "points": 10,
        "first_name": "John",
        "last_name": "Doe",
        "nickname": "TheGreatPlayer42",
        "grade": {
          "id": "64c80d38-e50f-4f39-a089-7bb613223ffc",
          "name_en": "Beginner",
          "name_ar": "مبتدئ",
          "points": 10
        }
      }
    ]
  }
]
Gamification

GET /leaderboard/by-category

Returns the best players per category

200 OK

Returns the best players per category, also returns the category without any players.

type
object[]
Response Content-Types: application/json
Response Example (200 OK) 
[
  {
    "id": "d162b927-912e-490d-bae6-e14dab16abf3",
    "category_": {
      "id": "f30d83b1-69d9-4edd-94a7-9c5003cd0942",
      "title": "الرياضيات",
      "icon_url": "https://madrasa.org/wp-content/themes/education_v2/imgs/vidLib/15.png",
      "slug": "الرياضيات",
      "created_at": "2018-12-03T09:04:42.000Z",
      "updated_at": "2018-12-03T09:04:42.000Z",
      "enabled": true,
      "weight": 0,
      "tags": [
        "toto"
      ]
    },
    "users": [
      {
        "points": 10,
        "id": "d162b927-912e-490d-bae6-e14dab16abf3",
        "first_name": "John",
        "last_name": "Doe",
        "nickname": "TheGreatPlayer42",
        "grade": {
          "id": "64c80d38-e50f-4f39-a089-7bb613223ffc",
          "name_en": "Beginner",
          "name_ar": "مبتدئ",
          "points": 10
        }
      }
    ]
  }
]
Gamification Lesson

GET /daily/lesson

returns the daily lesson

200 OK
Lesson

The daily lesson

Response Content-Types: application/json
Response Example (200 OK) 
{
  "id": "6f3d0648-37eb-4d5a-b7a0-86e63a1bdc53",
  "title": "عدّ الأرقام الصغيرة",
  "icon_url": "https://madrasa.org/wp-content/themes/education_v2/imgs/vidLib/15.png",
  "slug": "عدّ الأرقام الصغيرة",
  "created_at": "2018-12-03T09:05:50.000Z",
  "updated_at": "2018-12-03T09:05:50.000Z",
  "enabled": false,
  "weight": 1,
  "tags": [
    "عدّ الأرقام الصغيرة"
  ],
  "youtube_video_id": "2345678901",
  "description": "عدّ الأرقام الصغيرة",
  "sub_section_id": "0f6c6cd4-3379-45be-a28a-d05d2ae010ba"
}
Gamification

GET /badges/mine

returns a list of the badges won by the user

200 OK
BadgeCategory

returns a list of the badges won by the user

type
BadgeCategory
Response Example (200 OK) 
[
  {
    "id": "64c80d38-e50f-4f39-a089-7bb613223ffc",
    "name_en": "Learning Badge",
    "name_ar": "شارة التعلم",
    "gamification_badges": [
      {
        "id": "6f3d0648-37eb-4d5a-b7a0-86e63a1bdc53",
        "description_en": "daily badge",
        "description_ar": "شارة اليومية",
        "name_en": "daily badge",
        "name_ar": "شارة اليومية"
      }
    ]
  }
]
jwt_token
Gamification

GET /badges/by-category

returns the total list of badges by category

200 OK
BadgeCategory

returns the total list of badges by category

type
BadgeCategory
Response Content-Types: application/json
Response Example (200 OK) 
[
  {
    "id": "64c80d38-e50f-4f39-a089-7bb613223ffc",
    "name_en": "Learning Badge",
    "name_ar": "شارة التعلم",
    "gamification_badges": [
      {
        "id": "6f3d0648-37eb-4d5a-b7a0-86e63a1bdc53",
        "description_en": "daily badge",
        "description_ar": "شارة اليومية",
        "name_en": "daily badge",
        "name_ar": "شارة اليومية"
      }
    ]
  }
]
Gamification

GET /badges

returns the total list of badges with the category associated

200 OK
Badge

returns the total list of badges with the category associated

type
Badge
Response Content-Types: application/json
Response Example (200 OK) 
[
  {
    "id": "6f3d0648-37eb-4d5a-b7a0-86e63a1bdc53",
    "description_en": "daily badge",
    "description_ar": "شارة اليومية",
    "name_en": "daily badge",
    "name_ar": "شارة اليومية",
    "category_": {
      "id": "64c80d38-e50f-4f39-a089-7bb613223ffc",
      "name_en": "Learning Badge",
      "name_ar": "شارة التعلم"
    }
  }
]
Gamification

GET /points/history

returns the total history of the points earned

200 OK
Point

returns the total history of the points earned

type
Point
Response Content-Types: application/json
Response Example (200 OK) 
[
  {
    "id": "6f3d0648-37eb-4d5a-b7a0-86e63a1bdc53",
    "point": 10,
    "action": "video_completed",
    "created_at": "018-12-03T09:04:42.000Z"
  }
]
jwt_token
Gamification

GET /points/total

returns the total number of points

200 OK

returns the total number of points

type
object
Response Content-Types: application/json
Response Example (200 OK) 
{
  "total": 50,
  "current_grade": {
    "id": "64c80d38-e50f-4f39-a089-7bb613223ffc",
    "name_en": "Beginner",
    "name_ar": "مبتدئ",
    "points": 10
  },
  "grades": [
    {
      "id": "64c80d38-e50f-4f39-a089-7bb613223ffc",
      "name_en": "Beginner",
      "name_ar": "مبتدئ",
      "points": 10
    }
  ]
}
jwt_token

Schema Definitions

Grade: object

id: string
name_en: string
name_ar: string
points: number
Example
{
  "id": "64c80d38-e50f-4f39-a089-7bb613223ffc",
  "name_en": "Beginner",
  "name_ar": "مبتدئ",
  "points": 10
}

BadgeCategory: object

id: string
name_en: string
name_ar: string
gamification_badges: object[]
object
id: string
description_en: string
description_ar: string
name_en: string
name_ar: string
Example
{
  "id": "64c80d38-e50f-4f39-a089-7bb613223ffc",
  "name_en": "Learning Badge",
  "name_ar": "شارة التعلم",
  "gamification_badges": [
    {
      "id": "6f3d0648-37eb-4d5a-b7a0-86e63a1bdc53",
      "description_en": "daily badge",
      "description_ar": "شارة اليومية",
      "name_en": "daily badge",
      "name_ar": "شارة اليومية"
    }
  ]
}

Badge: object

id: string
description_en: string
description_ar: string
name_en: string
name_ar: string
category_: object
id: string
name_en: string
name_ar: string
Example
{
  "id": "6f3d0648-37eb-4d5a-b7a0-86e63a1bdc53",
  "description_en": "daily badge",
  "description_ar": "شارة اليومية",
  "name_en": "daily badge",
  "name_ar": "شارة اليومية",
  "category_": {
    "id": "64c80d38-e50f-4f39-a089-7bb613223ffc",
    "name_en": "Learning Badge",
    "name_ar": "شارة التعلم"
  }
}

Point: object

id: string
point: number
action: string
created_at: string
Example
{
  "id": "6f3d0648-37eb-4d5a-b7a0-86e63a1bdc53",
  "point": 10,
  "action": "video_completed",
  "created_at": "018-12-03T09:04:42.000Z"
}

Profile: object

id: string
first_name: string
last_name: string
date_of_birth: string
gender: string
city: string
type: string
updated_at: string
nationality_: Country
country_of_residence_: Country
Example
{
  "id": "6f3d0648-37eb-4d5a-b7a0-86e63a1bdc53",
  "first_name": "John",
  "last_name": "Doe",
  "date_of_birth": "1991-07-30",
  "gender": "female",
  "city": "Nancy",
  "type": "student",
  "updated_at": "2018-12-03T09:04:42.000Z",
  "nationality_": {
    "id": "f30d83b1-69d9-4edd-94a7-9c5003cd0942",
    "code": "TD",
    "name_en": "Chad",
    "name_ar": "تشاد"
  },
  "country_of_residence_": {
    "id": "f30d83b1-69d9-4edd-94a7-9c5003cd0942",
    "code": "TD",
    "name_en": "Chad",
    "name_ar": "تشاد"
  }
}

Lesson: object

id: string
title: string
icon_url: string
slug: string
created_at: string
updated_at: string
enabled: boolean
weight: number
tags: string[]
string
youtube_video_id: string
description: string
sub_section_id: string
Example
{
  "id": "6f3d0648-37eb-4d5a-b7a0-86e63a1bdc53",
  "title": "عدّ الأرقام الصغيرة",
  "icon_url": "https://madrasa.org/wp-content/themes/education_v2/imgs/vidLib/15.png",
  "slug": "عدّ الأرقام الصغيرة",
  "created_at": "2018-12-03T09:05:50.000Z",
  "updated_at": "2018-12-03T09:05:50.000Z",
  "enabled": false,
  "weight": 1,
  "tags": [
    "عدّ الأرقام الصغيرة"
  ],
  "youtube_video_id": "2345678901",
  "description": "عدّ الأرقام الصغيرة",
  "sub_section_id": "0f6c6cd4-3379-45be-a28a-d05d2ae010ba"
}

VideoActivity: object

id: string
type: string
lesson_: Lesson
Example
{
  "id": "5cf46551-b699-44ca-94c5-025e86685e32",
  "type": "completed",
  "lesson_": {
    "id": "6f3d0648-37eb-4d5a-b7a0-86e63a1bdc53",
    "title": "عدّ الأرقام الصغيرة",
    "icon_url": "https://madrasa.org/wp-content/themes/education_v2/imgs/vidLib/15.png",
    "slug": "عدّ الأرقام الصغيرة",
    "created_at": "2018-12-03T09:05:50.000Z",
    "updated_at": "2018-12-03T09:05:50.000Z",
    "enabled": false,
    "weight": 1,
    "tags": [
      "عدّ الأرقام الصغيرة"
    ],
    "youtube_video_id": "2345678901",
    "description": "عدّ الأرقام الصغيرة",
    "sub_section_id": "0f6c6cd4-3379-45be-a28a-d05d2ae010ba"
  }
}

Section: object

id: string
title: string
icon_url: string
slug: string
created_at: string
updated_at: string
enabled: boolean
weight: number
tags: string[]
string
category_id: string
Example
{
  "id": "5cf46551-b699-44ca-94c5-025e86685e32",
  "title": "العد",
  "icon_url": "https://madrasa.org/wp-content/themes/education_v2/imgs/vidLib/15.png",
  "slug": "العد",
  "created_at": "2018-12-03T09:05:50.000Z",
  "updated_at": "2018-12-03T09:05:50.000Z",
  "enabled": false,
  "weight": 0,
  "tags": [
    "العد"
  ],
  "category_id": "f30d83b1-69d9-4edd-94a7-9c5003cd0942"
}

Subsection: object

id: string
title: string
title_en: string
icon_url: string
slug: string
created_at: string
updated_at: string
weight: number
enabled: boolean
youtube_playlist_id: string
Example
{
  "id": "0f6c6cd4-3379-45be-a28a-d05d2ae010ba",
  "title": "الأعداد من 0 إلى 120",
  "title_en": "English Title",
  "icon_url": "https://madrasa.org/wp-content/themes/education_v2/imgs/vidLib/15.png",
  "slug": "الأعداد من 0 إلى 120",
  "created_at": "2018-12-03T09:04:42.000Z",
  "updated_at": "2018-12-03T09:04:42.000Z",
  "weight": 0,
  "enabled": true,
  "youtube_playlist_id": "1234567890"
}

Answer: object

id: string
created_at: string
value: strng
Example
{
  "id": "d19fbe0a-bd03-4fdc-9adb-2c99f6999215",
  "created_at": "2019-01-22T05:07:01.092Z",
  "value": "hello"
}

Watchlist: object

id: string

watchlist database id as uuid

example: f30d83b1-69d9-4edd-94a7-9c5003cd0942

created_at: string

The date the lesson has been added to the watchlist

example 2019-01-22T05:07:01.079Z

lesson_: Lesson
Example
{
  "id": "f30d83b1-69d9-4edd-94a7-9c5003cd0942",
  "created_at": "2019-01-22T05:07:01.079Z",
  "lesson_": {
    "id": "6f3d0648-37eb-4d5a-b7a0-86e63a1bdc53",
    "title": "عدّ الأرقام الصغيرة",
    "icon_url": "https://madrasa.org/wp-content/themes/education_v2/imgs/vidLib/15.png",
    "slug": "عدّ الأرقام الصغيرة",
    "created_at": "2018-12-03T09:05:50.000Z",
    "updated_at": "2018-12-03T09:05:50.000Z",
    "enabled": false,
    "weight": 1,
    "tags": [
      "عدّ الأرقام الصغيرة"
    ],
    "youtube_video_id": "2345678901",
    "description": "عدّ الأرقام الصغيرة",
    "sub_section_id": "0f6c6cd4-3379-45be-a28a-d05d2ae010ba"
  }
}

Question: object

id: string

question id as uuid

example: f30d83b1-69d9-4edd-94a7-9c5003cd0942

created_at: string

The date the question has been created

example 2019-01-22T05:07:01.079Z

order: number
status: string
type: string
value: string
begin_at: string
end_at: string
answer_type: string

The type of question, 'mcq' means multiple choice question, it's the only value supported for now

answers: Answer
Answer
lessson_: Lesson
Example
{
  "id": "f30d83b1-69d9-4edd-94a7-9c5003cd0942",
  "created_at": "2019-01-22T05:07:01.079Z",
  "order": 1,
  "status": "current",
  "type": "text",
  "value": "اشترى سمير تفاحًا وموزًا من البقالّة. إذا علمت أنّ ثمن التفاح 25.85 درهمًا والموز 20.655 درهمًا، وأنّ قيمة الضريبة المضافة عليهما معًا تبلغ 2.3 درهمًا، كم يجب أن يدفع سمير لصاحب البقالة؟",
  "begin_at": "2019-01-22T00:00:00.000Z",
  "end_at": "2019-01-23T00:00:00.000Z",
  "answer_type": "mcq",
  "answers": [
    {
      "id": "d19fbe0a-bd03-4fdc-9adb-2c99f6999215",
      "created_at": "2019-01-22T05:07:01.092Z",
      "value": "hello"
    }
  ],
  "lessson_": {
    "id": "6f3d0648-37eb-4d5a-b7a0-86e63a1bdc53",
    "title": "عدّ الأرقام الصغيرة",
    "icon_url": "https://madrasa.org/wp-content/themes/education_v2/imgs/vidLib/15.png",
    "slug": "عدّ الأرقام الصغيرة",
    "created_at": "2018-12-03T09:05:50.000Z",
    "updated_at": "2018-12-03T09:05:50.000Z",
    "enabled": false,
    "weight": 1,
    "tags": [
      "عدّ الأرقام الصغيرة"
    ],
    "youtube_video_id": "2345678901",
    "description": "عدّ الأرقام الصغيرة",
    "sub_section_id": "0f6c6cd4-3379-45be-a28a-d05d2ae010ba"
  }
}

Country: object

id: string
code: string
name_en: string
name_ar: string
Example
{
  "id": "f30d83b1-69d9-4edd-94a7-9c5003cd0942",
  "code": "TD",
  "name_en": "Chad",
  "name_ar": "تشاد"
}

Category: object

id: string
title: string
icon_url: string
slug: string
created_at: string
updated_at: string
enabled: boolean
weight: number
tags: string[]
string
Example
{
  "id": "f30d83b1-69d9-4edd-94a7-9c5003cd0942",
  "title": "الرياضيات",
  "icon_url": "https://madrasa.org/wp-content/themes/education_v2/imgs/vidLib/15.png",
  "slug": "الرياضيات",
  "created_at": "2018-12-03T09:04:42.000Z",
  "updated_at": "2018-12-03T09:04:42.000Z",
  "enabled": true,
  "weight": 0,
  "tags": [
    "toto"
  ]
}

UnauthorizedToken: object

message: string
Example
{
  "message": "Invalid or expired JWT"
}

InvalidUUid: object

message: string
Example
{
  "message": "Invalid id provided, please provide a valid uuid parameter"
}

AccessToken: object

accessToken: string
Example
{
  "accessToken": "<json_web_token>"
}

Error: object

message: string
Example
{
  "message": "string"
}
Documentation by Spectacle