Rattil API Documentation

To send authenticated request, add Authorization header to the request with Bearer {token} value.

To get JSON responses, add Accept header with application/json value.

All the URIs in this documentation has a prefix: /api/v1/.

APIs That need methods (PUT, PATCH), it should sent as POST request and include the needed method as an extra parameter _method.

Index

Responses
Authentication
Suwar
- Suwar list
- Show Sura information
Recitations
Profiles
Follow system
Likes system
- Like a recitation
- Un-Like a recitation
Favorites system
Comments
Reports
- Report a model
Assists APIs

Responses

Success response:

{
    "success": true,
    "message": "a text message"
}

Error response:

{
    "success": false,
    "message": "Error text message"
}

Validation error response:

{
    "success": false,
    "message": "Error text message",
    "errors": {
        "field-name": [ // array of errors messages
            "Error text message"
        ]
    }
}

Authentication

Login

url: login
method: POST
parameters:
- username required // email or username
- password required
response: a JSON response like:

{
    "success": true,
    "message": "Login success message",
    "user": {
        "id": 1,
        "name": "User Name",
        "username": "username",
        "email": "user@example.com",
        "token": "Authentication token"
    }
}

Logout

url: logout
method: GET
Authentication required
response: normal Success response.

Register

url: register
method: POST
parameters:
- name required // User full name
- username required
- email required
- password required
- password_confirmation required
response: normal Success response.

Reset password request

url: password/email
method: POST
parameters:
- email required
response: normal Success response.

Social media authentication

url: social/{provider} // available providers [facebook]
method: POST
parameters:
- oauth_token required // The access_token returned from the provider
response: a JSON response like:

{
    "success": true,
    "message": "Login success message",
    "user": {
        "id": 1,
        "name": "User Name",
        "username": "username",
        "email": "user@example.com",
        "token": "Authentication token"
    }
}

Suwar

Suwar list

url: /suwar
method: GET
Authentication Required
response: a JSON response with pagination like:

[   // arrau of models
    {
        "id": 1, // ID of sura
        "name": "test", // name of sura
        "revealed": "medinan",
        "chronologicalOrder": 1
    },
    {
        "id": 2,
        "name": "Test 2",
        "revealed": "medinan",
        "chronologicalOrder": 3
    }
]

Show Sura information

url: /suwar/{model} // {model} is The ID of Sura
method: GET
Authentication Required
response: a JSON response like:

{
  "id": 1,
  "name": "test",
  "revealed": "labels.medinan",
  "chronologicalOrder": 1,
  "verses": [ // Array of verses
     {
        "id": 1, // ID of verse
        "number": 1, // The number of verse
        "text":  "The text of verse",
        "cleanText":  "The clean text of verse",
        "characters":  "The characters of verse"
     }
  ]
}

Recitations

recitation list of an user

url: /recitations/list/{model?} // {model} is the user ID or username. if you leave it empty will return the recitations of logged in user.
method: GET
Authentication Required
response: a JSON response with pagination like:

{
  "total": 1, // total of user recitation
  "limit": 15, // number of recitations per page
  "currentPage": 1, // current page number
  "data": [ // array of recitation
    {
      "id": 2, // ID of recitation
      "slug": "xxxx",
      "user": { // The owner of recitation
        "id": 4,
        "name": "AbdulKader",
        "username": "abd",
        "avatar": null,
        "certified": false
      },
      "narration": { // Narration information
        "id": 1,
        "name": "Test",
        "weight": 2
      },
      "fromVerse": { // Start verse
        "id": 1,
        "number": 1,
        "text": "ssss",
        "cleanText": "ssss",
        "characters": "sss"
      },
      "toVerse": { // end Verse
        "id": 2,
        "number": 2,
        "text": "dddd",
        "cleanText": "dddd",
        "characters": "dddd"
      },
      "date": 1476232607, // Created date
      "commentsCount": 0, // number of comments
      "favoritesCount": 0, // number of favorites
      "likesCount": 0 // number of likes
    }
  ]
}

Recitation list of followed people

url: /recitations/following
method: GET
Authentication Required
response: a JSON response pagination like:

{
  "total": 1, // total of user recitation
  "limit": 15, // number of recitations per page
  "currentPage": 1, // current page number
  "data": [ // array of recitation
    {
      "id": 2, // ID of recitation
      "slug": "xxxx",
      "user": { // The owner of recitation
        "id": 4,
        "name": "AbdulKader",
        "username": "abd",
        "avatar": null,
        "certified": false
      },
      "narration": { // Narration information
        "id": 1,
        "name": "Test",
        "weight": 2
      },
      "fromVerse": { // Start verse
        "id": 1,
        "number": 1,
        "text": "ssss",
        "cleanText": "ssss",
        "characters": "sss"
      },
      "toVerse": { // end Verse
        "id": 2,
        "number": 2,
        "text": "dddd",
        "cleanText": "dddd",
        "characters": "dddd"
      },
      "date": 1476232607, // Created date
      "commentsCount": 0, // number of comments
      "favoritesCount": 0, // number of favorites
      "likesCount": 0 // number of likes
    }
  ]
}

Latest recitations list

url: /recitations/latest
method: GET
Authentication Required
response: a JSON response pagination like:

{
  "total": 1, // total of user recitation
  "limit": 15, // number of recitations per page
  "currentPage": 1, // current page number
  "data": [ // array of recitation
    {
      "id": 2, // ID of recitation
      "slug": "xxxx",
      "user": { // The owner of recitation
        "id": 4,
        "name": "AbdulKader",
        "username": "abd",
        "avatar": null,
        "certified": false
      },
      "narration": { // Narration information
        "id": 1,
        "name": "Test",
        "weight": 2
      },
      "fromVerse": { // Start verse
        "id": 1,
        "number": 1,
        "text": "ssss",
        "cleanText": "ssss",
        "characters": "sss"
      },
      "toVerse": { // end Verse
        "id": 2,
        "number": 2,
        "text": "dddd",
        "cleanText": "dddd",
        "characters": "dddd"
      },
      "date": 1476232607, // Created date
      "commentsCount": 0, // number of comments
      "favoritesCount": 0, // number of favorites
      "likesCount": 0 // number of likes
    }
  ]
}

Popular recitations list

url: /recitations/popular
method: GET
parameters:
- sort optional // can be [likes|comments|favorites] default is likes.
Authentication Required
response: a JSON response pagination like:

{
  "total": 1, // total of user recitation
  "limit": 15, // number of recitations per page
  "currentPage": 1, // current page number
  "data": [ // array of recitation
    {
      "id": 2, // ID of recitation
      "slug": "xxxx",
      "user": { // The owner of recitation
        "id": 4,
        "name": "AbdulKader",
        "username": "abd",
        "avatar": null,
        "certified": false
      },
      "narration": { // Narration information
        "id": 1,
        "name": "Test",
        "weight": 2
      },
      "fromVerse": { // Start verse
        "id": 1,
        "number": 1,
        "text": "ssss",
        "cleanText": "ssss",
        "characters": "sss"
      },
      "toVerse": { // end Verse
        "id": 2,
        "number": 2,
        "text": "dddd",
        "cleanText": "dddd",
        "characters": "dddd"
      },
      "date": 1476232607, // Created date
      "commentsCount": 0, // number of comments
      "favoritesCount": 0, // number of favorites
      "likesCount": 0 // number of likes
    }
  ]
}

Post new Recitation

url: /recitations
method: POST
Authentication required
parameters:
- sura_id required // The ID of recited Sura
- narration_id required // The ID of recite's narration
- from_verse required // ID of start verse
- to_verse required // ID of end verse
- file required // file of recitation
- description optional // The comment on the recitation
- mentions optional // should be array of users IDs That mentioned in the post
response: normal Success response.

Update Recitation

url: /recitations/{model} // {model} is the ID of recitation
method: POST
Authentication required
parameters:
- sura_id required // The ID of recited Sura
- narration_id required // The ID of recite's narration
- from_verse required // ID of start verse
- to_verse required // ID of end verse
- description optional // The comment on the recitation
- mentions optional // should be array of users IDs That mentioned in the post
response: normal Success response.

Delete Recitation

url: /recitations/{model} // {model} is the ID of recitation
method: Delete
Authentication required
response: normal Success response.

Listen Recitation

This end point increase the number of listeners of recitation.

url: /recitations/{model}/listen // {model} is the ID of recitation
method: POST
response: normal Success response.

Show Recitation information

url: /recitations/{model} // {model} is The ID of Recitation
method: GET
Authentication required
response: a JSON response like:

{
  "id": 2,
  "slug": "xxxx",
  "user": { // Owner information
    "id": 4,
    "name": "AbdulKader",
    "username": "abd",
    "avatar": null,
    "certified": false
  },
  "narration": { // Narration information
    "id": 1,
    "name": "Test",
    "weight": 2
  },
  "fromVerse": { // Start verse information
    "id": 1,
    "number": 1,
    "text": "ssss",
    "cleanText": "ssss",
    "characters": "sss"
  },
  "toVerse": { // end verse information
    "id": 2,
    "number": 2,
    "text": "dddd",
    "cleanText": "dddd",
    "characters": "dddd"
  },
  "date": 1476232607, // Created date timestamp
  "verified": false,
  "commentsCount": 0,
  "favoritesCount": 0,
  "likesCount": 0,
  "listenersCount": 0,
  "description": "xxxxx",
  "url": "xxxx",
  "sura": { // Sura information
    "id": 1,
    "name": "test",
    "verseCount": 2,
    "revealed": "labels.medinan",
    "chronologicalOrder": 1
  },
  "mentions": [], // Array of Mentioned users
  "verses": [ // Array of recited verses
    {
      "id": 1,
      "number": 1,
      "text": "ssss",
      "cleanText": "ssss",
      "characters": "sss"
    },
    {
      "id": 2,
      "number": 2,
      "text": "dddd",
      "cleanText": "dddd",
      "characters": "dddd"
    }
  ]
}

Search Recitations

url: /recitations/search
method: POST
parameters:
- keyword required // minimum 2 characters
- sura_id optional // could be an array or string with commas between Suwar IDs
- narration_is optional // could be an array or string with commas between narrations IDs
Authentication Required
response: a JSON response pagination like:

{
  "total": 1, // total of user recitation
  "limit": 15, // number of recitations per page
  "currentPage": 1, // current page number
  "data": [ // array of recitation
    {
      "id": 2, // ID of recitation
      "slug": "xxxx",
      "user": { // The owner of recitation
        "id": 4,
        "name": "AbdulKader",
        "username": "abd",
        "avatar": null,
        "certified": false
      },
      "narration": { // Narration information
        "id": 1,
        "name": "Test",
        "weight": 2
      },
      "fromVerse": { // Start verse
        "id": 1,
        "number": 1,
        "text": "ssss",
        "cleanText": "ssss",
        "characters": "sss"
      },
      "toVerse": { // end Verse
        "id": 2,
        "number": 2,
        "text": "dddd",
        "cleanText": "dddd",
        "characters": "dddd"
      },
      "date": 1476232607, // Created date
      "commentsCount": 0, // number of comments
      "favoritesCount": 0, // number of favorites
      "likesCount": 0 // number of likes
    }
  ]
}

Profiles

Update profile

url: /profiles
method: POST
parameters:
- name required // maximum 255 characters
- image optional // profile image file
- bio optional // Maximum 500 characters
- language_key optional // should be a key exists in languages database
- country optional // should be a key exists in countries database
- city optional
- gender optional // available values: [male|female]
- email_notification optional // boolean
- private optional // boolean
Authentication Required
response: normal Success response.

Upload a profile image

url: /profiles/{model}/avatar // {model} is the username or ID of logged in user
method: POST
parameters:
- image required // image file
Authentication Required
response: normal Success response.

Delete profile image

url: /profiles/{model}/avatar // {model} is the username or ID of logged in user
method: DELETE
Authentication Required
response: normal Success response.

Show profile information

url: /profiles/{model?} // {model} is the user ID or username. if you leave it empty will return the profile of logged in user.
method: GET
Authentication Required
response: a JSON response like:

{
    "id": 4,
    "name": "AbdulKader Zein Eddin",
    "username": "abd",
    "avatar": "http://rattil.app/public/profiles/a87ff679a2f3e71d9181a67b7542122c.jpg",
    "bio": "Bio text",
    "language_key": "en",
    "country": "SA",
    "city": "Al Riyad",
    "gender": "male",
    "email_notification": 1, // This variable will return only if the profile is for logged in user
    "private": 0, // This variable will return only if the profile is for logged in user
    "followed": 0, // 0 = Not followed, 2 = Pending acceptance, 1 = followed
    "followers_count": 0,
    "following_count": 0,
    "favorites_count": 0,
    "recitations_count": 0
}

Search users

url: /users/search
method: GET
parameters:
- query required // minimum 2 characters. search keyword
- certified optional // boolean
Authentication Required
response: a JSON response like:

{
  "total": 3,
  "limit": 15,
  "currentPage": 1,
  "data": [
    {
      "id": 7,
      "name": "Abdul Kader Zein Eddin",
      "username": "abd",
      "avatar": null,
      "country": "tr",
      "recitations_count": 0
    }
  ]
}

Follow system

Follow an user

url: /follows/{model} // {model} is the User ID or username to follow
method: POST
Authentication Required
response: normal Success response.

Un-Follow an user

url: /follows/{model} // {model} is the User ID or username to un-follow
method: DELETE
Authentication Required
response: normal Success response.

Delete a follower

url: /follows/{model}/follower // {model} is the User ID or username to delete
method: DELETE
Authentication Required
response: normal Success response.

Pending requests list

Return a list of un-confirmed "following requests" of a private user.

url: /profiles/{model}/followers/pending // {model} is the User ID or username of logged in user
method: GET
Authentication Required
response: a JSON response like:

{
  "total": 1,
  "limit": 15,
  "currentPage": 1,
  "data": [
    {
      "id": 7, // the request ID
      "user_id": 2, // the user ID
      "name": "Mohammad",
      "username": "mhd",
      "avatar": null,
      "certified": 0,
      "date": 1482620154 // request date
    }
  ]
}

Accept following request

url: /profiles/{model}/followers/pending/{id} // {model} is the User ID or username of logged in user, {id} is the Following request ID.
method: POST
Authentication Required
response: normal Success response.

Decline following request

url: /profiles/{model}/followers/pending/{id} // {model} is the User ID or username of logged in user, {id} is the Following request ID.
method: DELETE
Authentication Required
response: normal Success response.

The followers list of an user

url: /profiles/{model}/followers // {model} is the username or ID of user.
method: GET
Authentication Required
response: a JSON response like:

{
    "total": 1,
    "limit": 15,
    "currentPage": 1,
    "data": [ // Array of users
        {
            "id": 4,
            "name": "aboudeh",
            "username": "abd",
            "avatar": "http://rattil.app/public/profiles/a87ff679a2f3e71d9181a67b7542122c.jpg",
            "country": null,
            "recitations_count": 1
        }
    ]
}

The following list of an user

url: /profiles/{model}/following // {model} is the username or ID of user.
method: GET
Authentication Required
response: a JSON response like:

{
    "total": 1,
    "limit": 15,
    "currentPage": 1,
    "data": [ // Array of users
        {
            "id": 4,
            "name": "aboudeh",
            "username": "abd",
            "avatar": "http://rattil.app/public/profiles/a87ff679a2f3e71d9181a67b7542122c.jpg",
            "country": null,
            "recitations_count": 1
        }
    ]
}

Likes system

Like a recitation

url: /likes/recitation/{model} // {model} is the ID of recitation
method: POST
Authentication Required
response: normal Success response.

Un-Like a recitation

url: /likes/recitation/{model} // {model} is the ID of recitation
method: DELETE
Authentication Required
response: normal Success response.

Favorites system

Favorite a recitation

url: /favorites/{model} // {model} is the ID of recitation
method: POST
Authentication Required
response: normal Success response.

Un-Favorite a recitation

url: /favorites/{model} // {model} is the ID of recitation
method: DELETE
Authentication Required
response: normal Success response.

Favorites list of an user

url: /profiles/{model}/favorites // {model} is the username or ID of user.
method: GET
Authentication Required
response: a JSON response like:

{
    "total": 1,
    "limit": 15,
    "currentPage": 1,
    "data": [ // Array of favorites recitations
{
      "id": 2,
      "slug": "xxxx",
      "user": {
        "id": 4,
        "name": "abdulkader",
        "username": "abd",
        "avatar": "http://rattil.app/public/profiles/a87ff679a2f3e71d9181a67b7542122c.jpg",
        "country": null,
        "recitations_count": 1
      },
      "narration": {
        "id": 1,
        "name": "Test",
        "weight": 2
      },
      "fromVerse": {
        "id": 1,
        "number": 1,
        "text": "ssss",
        "cleanText": "ssss",
        "characters": "sss"
      },
      "toVerse": {
        "id": 2,
        "number": 2,
        "text": "dddd",
        "cleanText": "dddd",
        "characters": "dddd"
      },
      "date": 1476232607,
      "commentsCount": 0,
      "favoritesCount": 0,
      "likesCount": 0
    }    ]
}

Comments

Comments list

return the comments of a recitation

url: /recitations/{model}/comments // {model} is the ID of recitation
method: GET
Authentication required
response: a JSON response like:

{
    "total": 1,
    "limit": 15,
    "currentPage": 1,
    "data": [ // Array of comments
    {
      "id": 1,
      "text": "Test Comment",
      "url": null,
      "verified": false,
      "user": {
        "id": 4,
        "name": "abdulkader",
        "username": "abd",
        "avatar": "http://rattil.app/public/profiles/a87ff679a2f3e71d9181a67b7542122c.jpg",
        "verified": false
      },
      "date": 1476232607
    }
  ]
}

Add a new comment

url: /recitations/{model}/comments // {model} is the ID of recitation
method: POST
Authentication required
parameters:
- text required // Comment text
- file optional // audio file. Only for certified users
response: normal Success response.

Delete a comment

url: /comments/{model} // {model} is the ID of Comment
method: DELETE
Authentication required
response: normal Success response.

Reports

Report a model

url: /{type}/{model}/report // type is the type of model [recitations|comments], {model} is the ID of model
method: POST
Authentication required
parameters:
- reason_id required // Comment text
- message optional // description message, max:500 characters
response: normal Success response.

Assists APIs

Languages list

url: /assists/languages
method: GET
Authentication required
response: a JSON response like:

[
    {
        "key": "en",
        "name": "English"
    },
    {
        "key": "ar",
        "name": "العربية"
    }
]

Countries list

url: /assists/countries
method: GET
Authentication required
response: a JSON response like:

[
    {
        "key": "sa",
        "name": "Saudi Arabia"
    },
    {
        "key": "tr",
        "name": "Turkey"
    }
]

Narrations list

url: /assists/narrations
method: GET
Authentication required
response: a JSON response like:

[
    {
        "id": 1,
        "weight": 1,
        "name": "Test narration"
    }
]

Reasons list

Get the list of report's reasons.
It is related to the model that you want to report it.

url: /assists/reasons/{type} //available [comments|recitations]
method: GET
Authentication required
response: a JSON response like:

[
    {
        "id": 1,
        "name": "Reason of report"
    }
]

Files

documentation.md

Latest commit

History