Cinedata API Documentation

Version 1.0 | A JSON API for retrieving and managing information about movies

Endpoints Overview

Method URL Pattern Action
GET /v1/healthcheck Show application information
POST /v1/users Register a new user
PUT /v1/users/activated Activate a specific user
POST /v1/tokens/password-reset Generate a new password-reset token
PUT /v1/users/password Update the password for a specific user
POST /v1/tokens/authentication Generate a new authentication token
GET /v1/movies Show the details of all movies
POST /v1/movies Create a new movie
GET /v1/movies/:id Show the details of a specific movie
PATCH /v1/movies/:id Update the details of a specific movie
DELETE /v1/movies/:id Delete a specific movie

Endpoint Details

GET /v1/healthcheck

This endpoint will return some basic information about our API, including its current version number and operating environment.

Example Request:

curl cinedata.mahmud.pro/v1/healthcheck

Successful Response:

					{
						"status": "available",
						"system_info": {
							"environment": "production",
							"version": "v1.0.0-8-ge863d51"
						}
					}

POST /v1/users

This endpoint will register (or signing up) a new user. This endpoint will expect user to provide the following details for the new user in a JSON request body.

Accepted JSON key-value pair in request BODY:

Key Value Type Example
name string {"name":"alice"}
email string {"email":"youremail@example.com"}
password string {"password":"12134221"}

Example Request:

curl -X PUT -d '{"name": "alice", "email":"youremail@example.com", "password":"122345623"}' cinedata.mahmud.pro/v1/users

Successful Response:

					{
						"user": {
							"id": 1,
							"created_at": "2024-09-10T05:29:17-04:00",
							"name": "your_name",
							"email": "youremail@example.com",
							"activated": false
						}
					}

PUT /v1/users/activated

This endpoint will accept a JSON request body containing the plaintext activation token which they received in their email after registering a new user.

Accepted JSON key-value pair in request BODY:

Key Value Type Example
token string {"token":"Y7QCRZ7FWOWYLXLAOC2VYOLIPY"}

Example Request:

curl -X PUT -d '{"token": "ABCDEFGHIJKLMNOPQRSTUVWXYZ"}' cinedata.mahmud.pro/v1/users/activated

Successful Response:

					{
						"user": {
							"id": 1,
							"created_at": "2024-09-10T05:29:17-04:00",
							"name": "your_name",
							"email": "youremail@example.com",
							"activated": true
						}
					}

POST /v1/tokens/password-reset

This endpoint will accept a JSON request body containing the email address of the user whose password they want to reset. If the user with that email address exists in the database, and the user has already confirmed their email address by activating, then the user will receive an email containing a token.

Accepted JSON key-value pair in request BODY:

Key Value Type Example
email string {"email": "alice@example.com"}

Example Request:

curl -X POST -d '{"email": "alice@example.com"}' cinedata.mahmud.pro/v1/tokens/password-reset

Successful Response:

					{	
						"message": "an email will be sent to you containing password reset instructions"
					}

PUT /v1/users/password

This endpoint will accept a JSON request body containing new password and token then successful response will update the password for the specific user.

Accepted JSON key-value pair in request BODY:

Key Value Type Example
password string {"password":"12345678"}
token string {"token":"Y7QCRZ7FWOWYLXLAOC2VYOLIPY"}

Example Request:

curl -X PUT -d '{"password": "your_new_password", "token": "Y7QCRZ7FWOWYLXLAOC2VYOLIPY"}' cinedata.mahmud.pro/v1/users/password

Successful Response:

					{
						"message": "your password was successfully reset"
					}

POST /v1/tokens/authentication

This endpoint will accept a JSON request body containing the user's credentials (email and password) and will return a authentication token with expiry time.

Accepted JSON key-value pair in request BODY:

Key Value Type Example
email string {"email":"youremail@example.com"}
password string {"password":"12345678"}

Example Request:

curl -X PUT -d '{"email":"youremail@example.com", "password":"12345678"}' cinedata.mahmud.pro/v1/tokens/authentication

Successful Response:

				{
					"authentication_token": {
						"token": "XP5CCPHIIAVON3XBAT6RM3IP5Y",
						"expiry": "2024-09-11T09:51:51.379151Z"
					}
				}

GET /v1/movies

This endpoint will return a list of all movies in the database. This endpoint support filtering by specifying parameters.

Accepted Headers:

Key Value Example Value
Authorization Bearer your_authentication_token Bearer XP5CCPHIIAVON3XBAT6RM3IP5Y

Accepted Parameters:

Parameter Type Example Value
title string The Matrix
genres []string crime,drama (values must be comma separated with no whitespace)
page uint (positive integer) any value between 1 to 1000000
page_size uint (positive integer) any value between 1 to 100
sort string support sorting by "id", "title", "year", "runtime", "-id", "-title","-year", "-runtime". appending hyphen before value means sorting in descending order.

Example Request:

curl cinedata.mahmud.pro/v1/movies?title=black&genres=action,drama&page=1&page_size=5&sort=year

Successful Response:

					{
						"metadata": {
							"current_page": 1,
							"page_size": 5,
							"first_page": 1,
							"last_page": 1,
							"total_records": 1
						},
						"movies": [
							{
								"id": 2,
								"title": "Black Panther",
								"year": 2018,
								"runtime": "134 mins",
								"genres": [
									"sci-fi",
									"action",
									"adventure"
								],
								"version": 2
							}
						]
					}

POST /v1/movies

This endpoint will accept a JSON request body containing data for the movie the user want to create in the system.

Accepted Headers:

Key Value Example Value
Authorization Bearer your_authentication_token Bearer XP5CCPHIIAVON3XBAT6RM3IP5Y

Accepted JSON key-value pair in request BODY:

Key Value Type Example
title string {"title":"Black Panther"}
year uint (positive integer) {"year":2018}
runtime string {"runtime":"134 mins"}
genres []string {"runtime":["sci-fi","action","adventure"]}

Example Request:

curl -X POST -d '{"title":"Moana","year":2016,"runtime":107, "genres":["animation","adventure"]}' cinedata.mahmud.pro/v1/movies

Successful Response:

					{
						"movie": {
							"id": 12,
							"title": "Moana",
							"year": 2016,
							"runtime": "107 mins",
							"genres": [
								"adventure",
								"animation"
							],
							"version": 1
						}
					}

GET /v1/movies/:id

Requesting this endpoint user can retrieve details of a specific movie by its ID.

Accepted Headers:

Key Value Example Value
Authorization Bearer your_authentication_token Bearer XP5CCPHIIAVON3XBAT6RM3IP5Y

Accepted Parameters:

Parameter Type Example Value
:id uint (positive integer) 1,2,56,2121,45

Example Request:

curl cinedata.mahmud.pro/v1/movies/123

Successful Response: 

					{
						"movie": {
							"id": 123,
							"title": "Black Panther",
							"year": 2018,
							"runtime": "134 mins",
							"genres": [
								"sci-fi",
								"action",
								"adventure"
							],
							"version": 1
						}
					}

PATCH /v1/movies/:id

Requesting this endpoint with JSON body user can update the details of a specific movie by its ID.

Accepted Headers:

Key Value Example Value
Authorization Bearer your_authentication_token Bearer XP5CCPHIIAVON3XBAT6RM3IP5Y

Accepted Parameters:

Parameter Type Example Value
:id uint (positive integer) 1,2,56,2121,45

Accepted JSON key-value pair in request BODY:

Key Value Type Example
title string {"title":"Black Panther"}
year uint (positive integer) {"year":2018}
runtime string {"runtime":"134 mins"}
genres []string {"runtime":["sci-fi","action","adventure"]}

Example Request:

curl -X PATCH -d '{"year":2019}' cinedata.mahmud.pro/v1/movies/123

Successful Response:

					{
						"movie": {
							"id": 123,
							"title": "Black Panther",
							"year": 2019,
							"runtime": "134 mins",
							"genres": [
								"sci-fi",
								"action",
								"adventure"
							],
							"version": 2
						}
					}

DELETE /v1/movies/:id

Delete a specific movie from the database by its ID.

Accepted Headers:

Key Value Example Value
Authorization Bearer your_authentication_token Bearer XP5CCPHIIAVON3XBAT6RM3IP5Y

Accepted Parameters:

Parameter Type Example Value
:id uint (positive integer) 1,2,56,2121,45

Example Request:

curl -X DELETE cinedata.mahmud.pro/v1/movies/3

Successful Response:

					{
						"message": "movie successfully deleted"
					}