API Endpoints - bounswe/bounswe2018group7 GitHub Wiki

history-backend.herokuapp.com

V1

HTTP Status Code

For a successful request, it is 200 (if not specified).

For an unsuccessful request:

  • If the request format is malformed (e.g. missing request parameters) or the request parameters are not valid, 400 (Bad Request)
  • If the user is not logged-in, 401 (Unauthorized)
  • If the user does not have the authorization to perform the request, 403 (Forbidden)
  • If the resource related to the request is not found, 404 (Not Found)
  • If the request method is not supported, 405 (Method Not Allowed)

Response Body

For a successful request, it is a JSON which contains directly the attributes of the resource related to the request.

For an unsuccessful request, it is a JSON which contains a single key named errors. This key is an Array of Strings which are descriptive error messages.

Authentication

For requests that require a User, Authorization header must be provided with the value Token <token>. <token> is the auth_token returned in Signin response.

Endpoints

ANNOTATIONS

Get/List Annotation(s)

GET /api/v1/annotations/<id>
GET /api/v1/annotations/?target=<target_source_url>

Request Body:
None.

Response Body on Success:
If "<id>" is provided, the details of that Annotation will be returned (as in the "Create" response).
If <target_source_url> is provided, an Array of Annotations that belong to that target source will be returned. Each member of the Array will be a JSON as in the "Create" response.

NOTES:
* Guests cannot view Annotations.

Create Annotation

POST /api/v1/annotations/

Request Body:
{
  "body": <a JSON object of Annotation body>,
  "target": <a JSON object of Annotation target>
}

Response Body on Success (HTTP `201` will be returned):
See https://github.com/bounswe/bounswe2018group7/wiki/Annotation-Data-Model#general-structure-of-an-annotation

NOTES:
* "body" and "target" keys of the request must comply https://github.com/bounswe/bounswe2018group7/wiki/Annotation-Data-Model

Update Annotation

PATCH /api/v1/annotations/<id>/

Request Body:
Same as in `Create`.

Response Body on Success:
Same as in `Create`.

NOTE: Partial update is supported.

Delete Annotation

DELETE /api/v1/annotations/<id>/

Request Body:
None

Response Body on Success (HTTP `204` will be returned):
None

NOTE: Admins can delete any Annotations.

See HiStory Annotation Data Model.

See Annotation Media Upload.

AUTHENTICATION

Sign-Up

POST /api/v1/signup/

Request Body:
{
  "username": <a String of username>,
  "email": <a String of valid email address>,
  "password": <a String of password>,
  "password_confirmation": <a String of password confirmation>,
  "first_name": <a String of first name>,
  "last_name": <a String of last name>,
  "profile_picture": <a ImageFile>
}

Response Body on Success:
{
  "username": <a String of username>,
  "email": <a String of valid email address>,
  "first_name": <a String of first name>,
  "last_name": <a String of last name>,
  "admin": false,
  "confirmed": false,
  "banned": false,
  "profile_picture": <url of the Profile picture or null>
}

NOTE: A confirmation email will be sent to the provided `email` address.

Sign-In

POST /api/v1/signin/

Request Body:
{
  "identity": <a String of username or a valid email address> ,
  "password": <a String of password>
}

Response Body on Success:
{
  "username": <a String of username>,
  "email": <a String of valid email address>,
  "first_name": <a String of first name>,
  "last_name": <a String of last name>,
  "admin": <a Boolean which indicates whether the user has admin privileges or not>,
  "confirmed": <a Boolean which indicates whether the user has confirmed his/her email address or not>,
  "banned": <a Boolean which indicates whether the user has been banned from the system or not>,
  "profile_picture": <url of Profile picture or null>,
  "auth_token": <a String of authentication token if the user is confirmed and not banned, else null>
}

Sign-Out

POST /api/v1/signout/

Request Headers:
"Authorization": "Token <auth_token>"

Response Body on Success:
{}

Email Confirmation Flow

Client first sends the following request to the server:

POST /api/v1/email_confirmation/

Request Body:
{
  "email": <a String of email address to which a confirmation message will be sent> 
}

Response Body on Success:
{}

Server sends a message which contains a link in the format <frontend_base_confirmation_url>?token=<token> (<frontend_base_confirmation_url> is stored on the server). When the user click this link in email, he/she goes to <frontend_base_confirmation_url>. Then, client sends the following request to the server:

POST /api/v1/email_confirmation/

Request Body:
{
  "token": <token> 
}

Response Body on Success:
{}

Password Reset Flow

Client first sends the following request to the server:

POST /api/v1/password_reset/

Request Body:
{
  "email": <a String of email address to which a password reset message will be sent> 
}

Response Body on Success:
{}

Server sends a message which contains a link in the format <frontend_base_password_reset_url>?token=<token> (<frontend_base_password_reset_url> is stored on the server). When the user click this link in email, he/she goes to <frontend_base_password_reset_url>. Then, client sends the following request to the server:

POST /api/v1/password_reset/

Request Body:
{
  "token": <token>
  "password": <a String of new password>,
  "password_confirmation": <a String of password confirmation>,
}

Response Body on Success:
{}

COMMENTS

List Comments

GET /api/v1/comments/{?memory_post=<memory_post_id>}

Request Body:
None.

Response Body on Success:
If "memory_post" query parameter is provided, an array of comments that belongs to that Memory-Post will be returned.
Else, an array of comments that belongs to requesting User will be returned.

NOTES:
* Each element of the array will be a JSON object as in the response body in `Create` below.
* Comments will be sorted from oldest to the newest.

Create Comment

POST /api/v1/comments/

Request Body:
{
  "memory_post": <an Integer of Memory-Post ID>,
  "content": <a String of comment>
}

Response Body on Success (HTTP `201` will be returned):
{
  "id": <an Integer which is the ID of the Comment in the system>,
  "memory_post": <an Integer which is the ID of the Memory-Post to which this Comment belongs>,
  "username": <a String of username of the User to whom this Comment belongs>,
  "content": <a String of Comment>,
  "created": <a String in the format "dd-mm-YYYY HH:MM:SS">
}

Update Comment

Comments cannot be updated.

Delete Comment

DELETE /api/v1/comment/<id>/

Request Body:
None

Response Body on Success (HTTP `204` will be returned):
None

NOTE: Admins can delete any Comments.

MEDIA UPLOAD

This section provides general end-point for media upload on HiStory. Only image, video and audio files can be uploaded.

POST <one of media upload endpoints>

Request Body:
{
  "file": <A File object>
}

Response Body on Success:
{
  "file_url": <A String of URL for the uploaded file>
}

Available Media Upload Endpoints:

  • Annotation Media Upload:

    /api/v1/media_upload/annotation

MEMORY-POSTS

Get/List Memory-Post(s)

GET /api/v1/memory_posts/<id>/

Request Body:
None.

Response Body on Success:
If "<id>" is provided, only the details of that Memory-Post will be returned (as in the "Create" response).
Else:
{
  "count": <An Integer which is the number of total Memory-Posts on the system>,
  "next": <A String of URL which points to the next page of results>
  "previous": <A String of URL which points to the previous page of results>
  "results": <An Array of Memory-Posts, each Memory-Post will be represented as in the response of "Create">
}

NOTES:
* Each page of results contain 10 Memory-Posts.
* Guests cannot request specific Memory-Posts.
* Guests can only get last 10 Memory-Posts.

Create Memory-Post

POST /api/v1/memory_posts/

Request Body:
{
  "title": <a String of Memory-Title>,
  "time": <a JSON object (plain or as a String)>,
  "location": <A JSON-Array (plain or as a String), elements of which represent Memory-Location items>,
  "story[0]": <a String or File which is a part of Memory-Story>,
  "story[1]": <a String or File which is a part of Memory-Story>,
  "story[<index>]": <a String or File which is a part of Memory-Story>,
  ...
  "tags": <A JSON-Array (plain or as a String) of Strings>
}

Response Body on Success (HTTP `201` will be returned):
{
  "id": <An Integer which is the ID of the Memory-Post in the system>,
  "username": <a String of username of the owner of the Memory-Post>,
  "title": <a String of Memory-Title>,
  "time": <a JSON object which represents a Memory-Time> or null (if there is no Memory-Time)>,
  "location": <a JSON-Array elements of which represent Memory-Locations>,
  "story": <a JSON-Array elements of which represent a Memory-Story item>,
  "tags": <A JSON-Array of Strings>,
  "created": <a String in the format "dd-mm-YYYY HH:MM:SS">,
  "updated": <a String in the format "dd-mm-YYYY HH:MM:SS">,
  "reactions": {
                 "current_user_liked": null,
                 "like": 0,
                 "dislike": 0
               }
}

NOTES:
* "current_user_liked" is a Boolean with 3 states:
    * If the requesting User has liked the related Memory-Post, it will be `true`.
    * If the User has disliked the related Memory-Post, it will be `false`.
    * If the User has not reacted yet, it will be `null`.
* "like" and "dislike" are the total number of likes and dislikes the Memory-Post has.

Example for Memory-Post Creation

Request Body:

{
  "title": "My MemoryPost Title",
  "time": {"type": "duration", "data": ["1990", "2000"]},
  "location": [{"type": "path", "points": [["lat1", "lng1"], ["lat2", "lng2"]]}, {"type": "region", "name": "Istanbul"}],
  "story[0]": "My Story Text 1",
  "story[1]": <ImageFile:my_image.png>,
  "story[2]": <AudioFile:my_audio.mp3>,
  "story[3]": "My Story Text 2",
  "tags": ["tag1", "tag2", "tag3"]
}

Response Body:

{
  "id": 3,
  "username": "hiStory",
  "title": "My MemoryPost Title",
  "time": {"type": "duration", "data": ["1990", "2000"]},
  "location": [{"type": "path", "points": [["lat1", "lng1"], ["lat2", "lng2"]]}, {"type": "region", "name": "Istanbul"}],
  "story": [{"type": "text", "payload": "My Story Text 1"}, {"type":"image/png", "payload": "mysite.com/media/my_image.png"}, {"type":"audio/mp3", "payload": "mysite.com/media/my_audio.mp3"}, {"type": "text", "payload": "My Story Text 2"}],
  "tags": ["tag1", "tag2", "tag3"]
  "created": "28-10-2018 21:08:06",
  "updated": "28-10-2018 21:08:06",
  "reactions": {
                 "current_user_liked": null,
                 "like": 0,
                 "dislike": 0
               }
}

Note that in the response, "time", "location", "story" and "tags" are not Strings. "time" is a JSON object and the other 3 are Arrays.

Update Memory-Post

PATCH /api/v1/memory_posts/<id>/

Request Body:
Same as in `Create`.

Response Body on Success:
Same as in `Create`.

NOTE: Partial update is supported. To update only the `story` part of a Memory-Post, you should send all the parts (story[0], story[1], story[2], ...) of `story` in the request parameters even if only one (or several) of them is changed by the user.

Delete Memory-Post

DELETE /api/v1/memory_posts/<id>/

Request Body:
None

Response Body on Success (HTTP `204` will be returned):
None

NOTE: Admins can delete any Memory-Posts.

PROFILES

View Profile

GET /api/v1/profiles/<username>/

Request Body:
None

Response Body on Success:
In addition to the response body of Sign-Up, following key(s) will be present:
* If <username> parameter is provided: (Means current User is viewing another User's Profile)
  {
    "created_memory_posts": [ {"id": <id>, "title": <title>}, {"id": <id>, "title": <title>}, ... ]
  }
* If <username> parameter is not provided: (Means current User is viewing his/her Profile)
  {
    "created_memory_posts": [ {"id": <id>, "title": <title>}, {"id": <id>, "title": <title>}, ... ],
    "liked_memory_posts": [ {"id": <id>, "title": <title>}, {"id": <id>, "title": <title>}, ... ]
  }

Create Profile

Creating a Profile (Account) is done through Sign-Up.

Update Profile

PATCH /api/v1/profiles/

Request Body:
Same as in Sign-Up.

Response Body on Success:
Same as in Sign-Up.

NOTE:
If 'email' is updated, a confirmation email will be sent to the new email address and the User will be required to confirm again.

Ban/Unban Profile

PATCH /api/v1/profiles/<username>/

Request Body:
{
  "ban": <a Boolean; True if Profile (User) should be banned; False if Profile (User) should be unbanned>
}

Response Body on Success:
Same as in Sign-Up.

NOTES:
* If <username> parameter is not provided, the request will be processed as if *Update Profile*.

Delete Profile

DELETE /api/v1/profiles/<username>/

Request Body:
None

Response Body on Success (HTTP `204` will be returned):
None

NOTES:
* Users can delete only their Profiles.
* If <username> parameter is not provided, the profile of the requesting User will be deleted.
* Admins can delete any Profiles.

REACTIONS

Also see "reactions" key of the response body of Create Memory-Post.

Create/Update Reaction

POST /api/v1/reactions/

Request Body:
{
  "memory_post": <an Integer of Memory-Post ID>,
  "like": <a Boolean; true for like, false for dislike>
}

Response Body on Success:
{
  "id": <an Integer which is the ID of the Reaction in the system>,
  "memory_post": <an Integer which is the ID of the Memory-Post to which this Reaction belongs>,
  "username": <a String of username of the User to whom this Reaction belongs>,
  "like": <a Boolean; true for like, false for dislike>
}

Delete Reaction

DELETE /api/v1/reactions/<id>/

Request Body:
None

Response Body on Success (HTTP `204` will be returned):
None

NOTE: Admins can delete any Reactions.

RECOMMENDATIONS

Mechanism works as follows: Some Memory-Posts of the requesting User and some other Memory-Posts in the system are selected randomly. Then, every selected User Memory-Post is compared with the every other selected Memory-Post from the system based on tag similarity. Finally, a number of Memory-Posts that have the highest similarity scores are returned.

Get Recommendations

GET /api/v1/recommendations/

Request Body:
None

Response Body on Success:
An Array of Memory-Posts. Each Memory-Post will be in the form as in the response body of CREATE MEMORY-POST request.

SEARCH

User can search whatever he likes. Let text be the text written to the search bar. This method will bring every memory post related to this text. And it will also bring related users.

Search

POST /api/v1/search/

Request Body:
{
    "text" : <String to search>
}

Response Body on Success:
{
    "memory_posts": { "ids" : <Array of memory post ids>, "titles" : <Array of memory post titles> }, 
    "users": <Array of usernames related to text>
}

banner

⚠️ **GitHub.com Fallback** ⚠️