apiary.apib

FORMAT: 1A
HOST: http://http://localhost:5000

# REST API for Cinemas IS

> College project which aims to create Information System for Cinemas chain

**Project**: https://gitlab.com/Aisik/iis_best_team

**API specs**: https://github.com/Vondry/REST

## Data Structures

### City (object)
- id: 1 (number, required)
- name: City name (string, required)

### Cinema (object)
- id: 1 (number, required)
- name: Cinema name (string, required)
- street: Cinema street (string, required)
- postcode: 123456 (number, required)
- latitude: 40.71 (number, required)
- longtitude: 74.00 (number, required)  

### Movie (object)
- id: 1 (number, required)
- name: Movie name (string, required)
- description (string, required)
- times: 1541190611, 1541190611 (array[number], required) - Timestamp in seconds, when movies are beigin projected
- images: cover_image.png, ./another/img.jpg (array[string], required) - Images related to the movie. First image is the cover.
- rating: 70 (number, required)
- access: 12+ (string, nullable)
- genre: Movie genre (string, required)
- length: 155  (number, required) - Move length in minutes

### NewMovie (object)
- id: 1 (number, required)
- name: Movie name (string, required)
- description (string, required)
- images: cover_image.png, ./another/img.jpg (array[string], required) - Images related to the movie.
- trailers: https://youtube... (array[string], required) - Trailers related to the movie
- rating: 70 (number, required)
- access: 12+ (string, nullable)
- genres: Movie genre (array[string], required)
- length: 155  (number, required) - Move length in minutes

### Hall (object)
- id: 1 (number, required)
- name (string, required)
- seats (array[(array[number])], required) - every array in seats display seats row
    - 1, 1, 1, 1, 0, 0  (array[number], required) - Meaning of values: -1-no seat, 0-unavailable, 1-available
    - 1, 1, 1, 1, 0, 0  (array[number], required)

### Seat (object)
- row (number, required)
- column (number, required)

### SeatReservations (object)
- tariffId (number, required)
- count (number, required)

### ReservationBlueprint (object)
- user (object, required)
    - id (number, required) - if null then no user is not logged in
    - name (string) - if this field is not present, then user is already logged in
    - surname (string) - if this field is not present, then user is already logged in
    - email (string) - if this field is not present, then user is already logged in
- cinemaId (number, required)
- movieId (number, required)
- movieTime (number, required)
- hallId (number, required)
- reservations (array[SeatReservations], required)
- price (number, required)
- seats (array[Seat], required)

### StatusObject (object)
- status: {success|failure} (string, required)
- errors: Error1, Error2 (array[string], required)

### ReservationStatusObject (object)
- id (number, required) - Unique reservation id used to match client's reservation
- Include StatusObject

### Tariff (object)
- id (number, required)
- type: Adult (string, required)
- price: 169 (number, required) 

### TokenPayload (object)
- id (number, required) - user id
- role (string, required) - user role e.g. cashier, manager, CEO, admin,...
- created (number, required) - timestamp when token was created
- exp (number, required) - expiration time of token in seconds

### TokenResponse (object)
- tokenType: Bearer (string, required) - Authorization: <tokenType> <token>
- acccessToken (string, required) - JWT short-lived token (20s)
- resfreshToken (string, required) - JWT long-lived token (1min)

### User (object)
- id (number)
- name (string, required)
- surname (string, required)
- email (string, required)
- city (string)
- street (string)
- houseNumber (number)
- postcode (number)
- phoneNumber (number)
- password (string, required)
- role (string)

### Reservation (object)
- id (number, required)
- user (object, required)
    - id (number, required) - id of logged or anonymous user
    - name (string, required)
    - surname (string, required)
    - email (string, required)
- reservations (array[SeatReservations], required)
- price (number, required)
- created (number, required) - timestamp in ms, when reservation was created
- payed (number, required) - timestamp in ms, when reservation was payed
- updated (number, required) - timestamp in ms, when reservation was last edited
- deleted (number, required) - timestamp in ms, when reservation was last deleted
- projectionId (number, required)

### UserReservation (object)
- id (number, required)
- reservations (array[SeatReservations], required)
- price (number, required)
- created (number, required) - timestamp in ms, when reservation was created
- payed (number, required) - timestamp in ms, when reservation was payed
- updated (number, required) - timestamp in ms, when reservation was last edited
- deleted (number, required) - timestamp in ms, when reservation was last deleted

### ReservationTicket (object)
- hallName (string, required) - name of hall where projection takes place
- movieName (string, required)
- projectionTime (string, required) - when projection for movie starts
- seatCol (number, required)
- seatRow (number, required)
- price (number, required)
- paymentType (string, required) - payment type of the ticket - (Student, Adult, ZTP,...)

### Projection (object)
- language (string, required)
- subtitles (string)
- cinemaId (number, required)
- hallId (number, required)
- movieId (number, required)
- movieTime (number, required)
- cinemaName (string, required)

### GlobalDashboard
- paid (number, required) - total amount of money for already payed reservations
- unpaid (number, required) - total amount of money for not yet payed reservations
- reservations (array, required) - aggregated count of reservations which was paied or unpaid each day
    - (object)
        - time (number, required) - timestamp
        - paid (number, required) - count of reservation which was paid
        - unpaid (number, required) - count of reservation which was not paid

# Group Reservation

Data related to reservation system

## Cities Collection [/cities]

### List all cities [GET]

+ Response 200 (application/json)
    
    + Attributes (array[City])
    
## Cinemas Collection [/cinemas]

### List all cinemas [GET]

+ Response 200 (application/json)
    
    + Attributes (array[Cinema])
    
## Cinemas in Cities [/cities/cinemas]

### List all cinemas associated to cities [GET]

+ Response 200 (application/json)

    + Attributes (array)
        - (object)
            - Include City
            - cinemas (array[number])

## List Movies associated to cinema [/cinemas/{id}/movies]

### Movies in cinemas  [GET]

+ Parameter
    - id (number) - Cinema id

+ Response 200 (application/json)
 
    + Attributes (array[Movie])
    
## Movies for given day [/cinemas/{id}/movies/{movieTime}]

### Specific movies in cinemas  [GET]

+ Parameter
    - id (number) - Cinema id
    - movieTime (number) - Timestamp for movie. Units which matters year, month, day

+ Response 200 (application/json)
 
    + Attributes (array[Movie])

## Reservation check [/reservation/validate]

- Checks validity of reservation.

### Check reservation validity  [POST]

+ Request (application/json)
    + Attributes
        - Include ReservationBlueprint

+ Response 200 (application/json)
     + Attributes (object)
        - Include ReservationStatusObject
        
+ Response 400 (application/json)
     + Attributes (object)
        - Include ReservationStatusObject

## Reservation [/reservation]

### Make reservation  [POST]

- Validity of reservation needs to be checked also! 
- If everything checks out, then reservation is made.

+ Request (application/json)
    + Attributes
       - Include ReservationBlueprint

+ Response 200 (application/json)
     + Attributes (object)
        - Include ReservationStatusObject
        
+ Response 400 (application/json)
     + Attributes (object)
        - Include ReservationStatusObject

# Group Movies

Data related to movies

## Get All Movies [/movies]

### Get all Movies  [GET]

+ Response 200 (application/json)
 
    + Attributes (array[Movie])
        

### Create Movie [PUT]

###### Access rights: `cashier`, `manager`, `CEO`

+ Request Headers

        Authorization: <tokenType> <token>

+ Request (application/json)
    + Attributes 
        - Include NewMovie
       
+ Response 200 (application/json)

+ Response 400 (application/json)
    + Attributes 
        - errors (array[string])
        
+ Response 401 (application/json)
    + Attributes 
        - errors (array[string])
        
+ Response 403 (application/json)
    + Attributes 
        - errors (array[string])

## Movie [/movies/{id}]

### Get speecific Movie  [GET]

+ Parameter
    - id (number) - Movie id

+ Response 200 (application/json)
    + Attributes 
        - Include Movie

### Delete Movie [DELETE]

###### Access rights: `cashier`, `manager`, `CEO`

+ Parameter
    - id (number) - Movie id

+ Request Headers

        Authorization: <tokenType> <token>

+ Response 200 (application/json)

+ Response 400 (application/json)
    + Attributes 
        - errors (array[string])
        
+ Response 401 (application/json)
    + Attributes 
        - errors (array[string])
        
+ Response 403 (application/json)
    + Attributes 
        - errors (array[string])

        

# Group Hall

Data related to halls

## Halls collection [/halls]

### List all halls [GET]

+ Response 200 (application/json)
    
    + Attributes (array[Hall])

## Hall related to movie [/halls?cinema={cinemaId}&movie={movieId}&time={time}]

### Movie hall [GET]

+ Parameter
    - cinemaId (number) - Cinema id
    - movieId (number) - Movie id
    - time (number) - Time when movie is played in given Cinema

+ Response 200 (application/json)
 
    + Attributes 
        - Include Hall
        

# Group Tariff

## Get available tariffs [/tariffs]

### Tariffs [GET]
+ Response 200 (application/json)
 
    + Attributes (array[Tariff])

# Group Registration

## Register user [/registrate]

> **200** - Registration succedded

> **400** - Registration has **failed**, due to:
- Missing some of required fields
- Invalid syntax of fields
- ...

### Register [POST]

+ Request (application/json)
    + Attributes
        - Include User

+ Response 200 (application/json)

+ Response 400 (application/json)
    + Attributes 
        - errors (array[string])

# Group Auth

## Authenticate user [/authentication]

### Authenticate [POST]

> **200** - Login has **succeded** and user obtains `TokenResponse`

> **400** - Login has **failed**, due to:
- Missing email or password
- Invalid email or password

As a result, user needs to authenticate again.

+ Request (application/json)
    + Attributes
       - email (string) - user email
       - password (string) - user password

+ Response 200 (application/json)
    + Attributes 
        - Include TokenResponse
        
+ Response 400 (application/json)
    + Attributes 
        - errors (array[string])
    
## Refresh authentication [/authentication/refresh]

### Refresh [POST]

> **200** - Refresh token is sucessfully **verified**. And user receives new `Access token`

> **401** - Refresh token may **expired** or does not have other parts valid. User needs to log-in again.

> **422** - Refresh token is **malformed**. User needs to log-in again

+ Request Headers

        Authorization: <tokenType> <refreshToken>

+ Response 200 (application/json)
    + Attributes 
        - accessToken (string) - access token
    
+ Response 401 (application/json)
    + Attributes 
        - errors (array[string])
        
+ Response 422 (application/json)
    + Attributes 
        - errors (array[string])ha


# Group CMS

**Content Management System**

> **401** - Access token **expired**. User may try to obtain fresh Access token using Refresh token.

> **403** - Access token **is valid**, but user is **not authorized** to access request data.

> **422** - Access token is **malformed**. User needs to log-in again

#### Roles
`user`, `cashier`, `manager`, `CEO`, `admin`


## Reservations [/reservations]

### Get all reservations [GET]

###### Access rights: `cashier`,  `manager`, `CEO`

+ Request Headers

        Authorization: <tokenType> <accessToken>
        
+ Response 200 (application/json)
 
    + Attributes (array[Reservation])
    
+ Response 400 (application/json)
    + Attributes 
        - errors (array[string])
        
+ Response 401 (application/json)
    + Attributes 
        - errors (array[string])
        
+ Response 403 (application/json)
    + Attributes 
        - errors (array[string])

## Update Reservations [/reservations/{id}]

### Update reservation [PATCH]

###### Access rights: `cashier`, `manager`, `CEO`

- may include parts or whole reservation. Received reservation should be merged to the old one, which overwrites.

+ Parameter
    - id (number)

+ Request Headers

        Authorization: <tokenType> <token>

+ Request (application/json)
    + Attributes 
        - Include Reservation
       
+ Response 200 (application/json)
 
    + Attributes (array[Reservation])

+ Response 400 (application/json)
    + Attributes 
        - errors (array[string])
        
+ Response 401 (application/json)
    + Attributes 
        - errors (array[string])
        
+ Response 403 (application/json)
    + Attributes 
        - errors (array[string])

## Print Reservations [/reservations/{id}/tickets]

### Get reservation for print [GET]

> For each Reservation there may be `x` PrintableReservations 
`Count of seats in Reservations == Count of PrintableReservations for one Reservation`

###### Access rights: `cashier`,  `manager`, `CEO`

+ Request Headers

        Authorization: <tokenType> <accessToken>
        
+ Response 200 (application/json)
 
    + Attributes (array[ReservationTicket])
    
+ Response 400 (application/json)
    + Attributes 
        - errors (array[string])
        
+ Response 401 (application/json)
    + Attributes 
        - errors (array[string])
        
+ Response 403 (application/json)
    + Attributes 
        - errors (array[string])
        
## Projections [/projections]

### Get all projections [GET]

###### Access rights: `cashier`,  `manager`, `CEO`

+ Request Headers

        Authorization: <tokenType> <accessToken>
        
+ Response 200 (application/json)
 
    + Attributes (array[Projection])
    
+ Response 400 (application/json)
    + Attributes 
        - errors (array[string])
        
+ Response 401 (application/json)
    + Attributes 
        - errors (array[string])
        
+ Response 403 (application/json)
    + Attributes 
        - errors (array[string])

### Create Projection [PUT]

###### Access rights: `cashier`, `manager`, `CEO`

+ Request Headers

        Authorization: <tokenType> <token>

+ Request (application/json)
    + Attributes 
        - Include Projection
       
+ Response 200 (application/json)

+ Response 400 (application/json)
    + Attributes 
        - errors (array[string])
        
+ Response 401 (application/json)
    + Attributes 
        - errors (array[string])
        
+ Response 403 (application/json)
    + Attributes 
        - errors (array[string])

## Delete Projection [/projections/{id}]

### Delete Projection [DELETE]

###### Access rights: `cashier`, `manager`, `CEO`

+ Parameter
    - id (number) - Projection id

+ Request Headers

        Authorization: <tokenType> <token>

+ Response 200 (application/json)

+ Response 400 (application/json)
    + Attributes 
        - errors (array[string])
        
+ Response 401 (application/json)
    + Attributes 
        - errors (array[string])
        
+ Response 403 (application/json)
    + Attributes 
        - errors (array[string])

## User [/users/{id}]

### Get User [GET]

###### Access rights: `EVERYONE` logged in can get data on himself

+ Request Headers

        Authorization: <tokenType> <accessToken>

+ Parameter
    - id (number) - User id
 
+ Response 200 (application/json)
    + Attributes 
        - Include User
    
+ Response 400 (application/json)
    + Attributes 
        - errors (array[string])
        
+ Response 401 (application/json)
    + Attributes 
        - errors (array[string])
        
+ Response 403 (application/json)
    + Attributes 
        - errors (array[string])

### Update User account [PATCH]

###### Access rights: `EVERYONE` logged in can update owned account

+ Request Headers

        Authorization: <tokenType> <accessToken>

+ Parameter
    - id (number) - User id
    
+ Request (application/json)
    + Attributes 
        - Include User
 
+ Response 200 (application/json)

+ Response 400 (application/json)
    + Attributes 
        - errors (array[string])
        
+ Response 401 (application/json)
    + Attributes 
        - errors (array[string])
        
+ Response 403 (application/json)
    + Attributes 
        - errors (array[string])

### Delete User account [DELETE]

###### Access rights: `EVERYONE` logged in can delete account to yourself. 
###### Additionall access rights: `CEO`, `admin` may delete account to other users

+ Request Headers

        Authorization: <tokenType> <accessToken>

+ Parameter
    - id (number) - User id
 
+ Response 200 (application/json)

+ Response 400 (application/json)
    + Attributes 
        - errors (array[string])
        
+ Response 401 (application/json)
    + Attributes 
        - errors (array[string])
        
+ Response 403 (application/json)
    + Attributes 
        - errors (array[string])

### User reservations [/users/{id}/reservations]

### List user reservations [GET]

###### Access rights: `EVERYONE` logged in can view owned reservations. 

+ Request Headers

        Authorization: <tokenType> <accessToken>

+ Parameter
    - id (number) - User id

+ Response 200 (application/json)
    + Attributes (array[UserReservation])
    
+ Response 400 (application/json)
    + Attributes 
        - errors (array[string])
        
+ Response 401 (application/json)
    + Attributes 
        - errors (array[string])
        
+ Response 403 (application/json)
    + Attributes 
        - errors (array[string])
        

### User refreshTokens [/users/{id}/refreshTokens]

### List refreshTokens [GET]

###### Access rights: `EVERYONE` logged in may view owned refreshTokens
###### Additional access rights: `admin` may view refreshTokens of others


+ Request Headers

        Authorization: <tokenType> <accessToken>

+ Parameter
    - id (number) - User id

+ Response 200 (application/json)
    + Attributes (array)
        - (object)
            - id
            - refreshToken
    
+ Response 400 (application/json)
    + Attributes 
        - errors (array[string])
        
+ Response 401 (application/json)
    + Attributes 
        - errors (array[string])
        
+ Response 403 (application/json)
    + Attributes 
        - errors (array[string])
        
### User refreshTokens [/users/{userId}/refreshTokens/{tokenId}]

### List refreshTokens [DELETE]

###### Access rights: `EVERYONE` logged in may delete owned refreshTokens
###### Additional access rights: `admin` may delete refreshTokens to others

+ Request Headers

        Authorization: <tokenType> <accessToken>

+ Parameter
    - userId (number) - User id
    - tokenId (number) - Refresh token id

+ Response 200 (application/json)

+ Response 400 (application/json)
    + Attributes 
        - errors (array[string])
        
+ Response 401 (application/json)
    + Attributes 
        - errors (array[string])
        
+ Response 403 (application/json)
    + Attributes 
        - errors (array[string])
        
### Admin [/users/{id}/roles]

### Change user role [PATCH]

###### Access rights: `CEO`, `admin`

When Role is changed, then all access and refresh tokens, for that user, are lost.

+ Request Headers

        Authorization: <tokenType> <accessToken>

+ Parameter
    - id (number) - User id

+ Request (application/json)
    + Attributes
       - role (string) - new user role
       
+ Response 200 (application/json)

+ Response 400 (application/json)
    + Attributes 
        - errors (array[string])
        
+ Response 401 (application/json)
    + Attributes 
        - errors (array[string])
        
+ Response 403 (application/json)
    + Attributes 
        - errors (array[string])
        
        
### Dashboards [/dashboards/global]

### Global statistics [GET]

###### Access rights:  `manager`, `CEO`

+ Request Headers

        Authorization: <tokenType> <accessToken>

+ Response 200 (application/json)
    + Attributes
        - Include GlobalDashboard
+ Response 400 (application/json)
    + Attributes 
        - errors (array[string])
        
+ Response 401 (application/json)
    + Attributes 
        - errors (array[string])
        
+ Response 403 (application/json)
    + Attributes 
        - errors (array[string])