# Flamby (Government)’s API documentation

This is the documentation for [Flamby (Government)](https://flamxby.herokuapp.com/docs)’s API.

#### Contents

- [Overview](#1-overview)
- [Authentication](#2-authentication)
- [JWT tokens]()
- [Resources](#3-resources)
- [Users](#31-users)
- [Reservations]()

## 1. Overview

Flamby (Government)’s API is a JSON-based API. All requests are made to endpoints beginning:
`https://flamxby.herokuapp.com/`

All requests must be secure, i.e. `https`, not `http`.

## 2. Authentication

In order to access some functions, you will need an access token.
An access token grants limited access to a user’s account. We offer one way to acquire an access token: **JWT tokens**.

### 2.1. JWT tokens

If you already have an existing integration, the first step is to acquire a short term authorization code by sending the user to our authorization URL so they can grant access to your integration.

https://flamxby.herokuapp.com/user/

With the following request body:

| Field | Type | Required? | Description |
|------------|--------|-----------|------------------------------------------------------------|
| name | string | required | The name of the user e.g., "Peter" |
| surname | string | required | The surname of the user e.g., "Parker" |
| citizen_id | string | required | The citizen id of the user (13 digits) e.g., "1134506547512" |
| birth_date | date | required | The birthdate of the user e.g., "2001-08-21" |
| occupation | string | required | The occupation of the user e.g., "Doctor" |
| address | string | required | The address of the user e.g., "Bangkok" |
| password | string | required | The password of the user e.g., "Verystrongpassword" |

The following permissions are available:

| Permission | Description |
| -------------------| ------------------------------------------------------------------ |
| Create reservation | Grants the ability to create a reservation. |
| Update reservation | Grants the ability to update a reservation. |
| Delete reservation | Grants the ability to delete a reservation. |

Once you have an authorization code, you may exchange it for a 60 minute access token with which you can make authenticated requests on behalf of the user. To acquire an access token, make a form-encoded server-side POST request:

POST /login HTTP/1.1
Host: flamxby.herokuapp.com
Content-Type: application/x-www-form-urlencoded
Accept: application/json
Accept-Charset: utf-8

If successful, you will receive back an access token response:

HTTP/1.1 201 OK
Content-Type: application/json; charset=utf-8

{
  "access_token": {{access_token}}, 
  "token_type": "bearer",
}

With the following parameters:

| Parameter | Type | Required? | Description |
| ------------- |--------------|------------|-------------------------------------------------|
| `token_type` | string | required | The literal string "bearer" |
| `access_token` | string | required | A token that is valid for 60 minutes and may be used to perform authenticated requests on behalf of the user. |

Access tokens is consecutive strings of base 64, like this:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxODE4MTgxODE4MTgxIiwiZXhwIjoxNjM0OTE5NzEwfQ.It8ku-DPba46Cs-uaB3aFictF-7WrhOtyyNFmxPQbok

## 3. Resources

Our API is using RESTful and we arranged around resources. All requests must be made with an integration token and made using `https`.

### 3.1. Users

#### Getting the authenticated user’s details
Returns details of the user who has granted permission to the application.

GET https://flamxby.herokuapp.com/user/{citizen_id}

Example request:

GET /user/1234123412341 HTTP/1.1
Host: flamxby.herokuapp.com
Content-Type: application/json
Accept: application/json

The response is a User object within a data envelope.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "user_id": 1,
  "name": "foo",
  "surname": "rock",
  "citizen_id": "1234123412341",
  "occupation": "programmer",
  "address": "bkk",
  "reservations": [
    {
      "reservation_id": 1,
      "register_timestamp": "2021-10-22T14:21:35.372000"
    }
  ]
}

Where a User object is:

| Field | Type | Description |
|------------|--------|------------------------------------------------------------|
| user_id | integer| The id of the user e.g., 1 |
| name | string | The name of the user e.g., "Peter" |
| surname | string | The surname of the user e.g., "Parker" |
| citizen_id | string | The citizen id of the user (13 digits) e.g., "1134506547512" |
| occupation | string | The occupation of the user e.g., "Doctor" |
| address | string | The address of the user e.g., "Bangkok" |
| reservations | string | The list of the user’s reservations |
| reservation_id | integer | The id of the specific reservation e.g., 1 |
| register_timestamp | datetime | The datetime as an ISO format e.g., "2021-10-22T14:52:14.933Z" |

Possible errors:

| Error code | Description |
| ---------------------|-------------------------------------------------|
| 404 Not found | Send a request but no object was found. |

### 3.2. Reservations

#### Listing all the reservation

This endpoint lets you get all the reservations of all the users.

The REST API endpoint exposes this list of reservations as a collection of resources under the user. A request to fetch a list of reservations for a user looks like this:

GET https://flamxby.herokuapp.com/reservation/

The response is a list of the reservations. An empty list is returned if there are no reservations.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
   {
      "reservation_id":1,
      "register_timestamp":"2021-10-22T14:21:35.372000",
      "owner":{
         "name":"foo",
         "surname":"rock",
         "birth_date":"2021-10-22",
         "citizen_id":"1234123412341",
         "occupation":"programmer",
         "address":"bkk"
      }
   }
]

Where a Reservation Object is:

| Field | Type | Description |
| ------------|--------|-------------------------------------------------|
| reservation_id | integer | The id of the specific reservation e.g., 1 |
| register_timestamp | datetime | The datetime as an ISO format e.g., "2021-10-22T14:52:14.933Z" |
| name | string | The name of the user e.g., "Peter" |
| surname | string | The surname of the user e.g., "Parker" |
| birth_date | date | required | The birthdate of the user e.g., "2001-08-21" |
| citizen_id | string | The citizen id of the user (13 digits) e.g., "1134506547512" |
| occupation | string | The occupation of the user e.g., "Doctor" |
| address | string | The address of the user e.g., "Bangkok" |

#### Create a reservation for the user

This endpoint lets you create a reservation with the register_timestamp (datetime in ISO format) as a request body. The user needs to be authorized.

POST https://flamxby.herokuapp.com/reservation/

With the following request body:

| Field | Type | Description |
| ------------|--------|-------------------------------------------------|
| register_timestamp | datetime | The datetime as an ISO format e.g., "2021-10-22T14:52:14.933Z" |

In the response, the user is presented with the reservation id, register timestamp, and the information of the user. An example response looks like this:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
   "reservation_id":2,
   "register_timestamp":"2021-10-22T16:17:13.275000",
   "owner":{
      "name":"pitchapa",
      "surname":"sae-lim",
      "birth_date":"2001-05-18",
      "citizen_id":"1818181818181",
      "occupation":"engineer",
      "address":"heaven"
   }
}

Where a Reservation Object is:

| Field | Type | Description |
| ------------|--------|-------------------------------------------------|
| reservation_id | integer | The id of the specific reservation e.g., 1 |
| register_timestamp | datetime | The datetime as an ISO format e.g., "2021-10-22T14:52:14.933Z" |
| name | string | The name of the user e.g., "Peter" |
| surname | string | The surname of the user e.g., "Parker" |
| birth_date | date | required | The birthdate of the user e.g., "2001-08-21" |
| citizen_id | string | The citizen id of the user (13 digits) e.g., "1134506547512" |
| occupation | string | The occupation of the user e.g., "Doctor" |
| address | string | The address of the user e.g., "Bangkok" |

Possible errors:

| Error code | Description |
| ---------------------|-------------------------------------------------|
| 404 Not found | Send a request but no object was found.|
| 422 Unprocessable Entity| Validation Error |

#### Get reservation from reservation's id

This endpoint lets you get a specific reservation using the reservation's id as a parameter.

A request to fetch a specific reservation using reservation's id looks like this:

GET https://flamxby.herokuapp.com/reservation/{reservation_id}

With the following parameter:

| Parameter | Description |
| ------------|-------------------------------------------------|
| reservation_id | The id of the specific reservation as an integer e.g., 1|

The response is the reservation information with the information of the user that is the owner. A message saying "No reservation with this id" is returned if there are no reservations with the specific id.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
   "reservation_id":1,
   "register_timestamp":"2021-10-22T14:21:35.372000",
   "owner":{
      "name":"foo",
      "surname":"rock",
      "birth_date":"2021-10-22",
      "citizen_id":"1234123412341",
      "occupation":"programmer",
      "address":"bkk"
   }
}

Where a Reservation Object is:

| Field | Type | Description |
| ------------|--------|-------------------------------------------------|
| reservation_id | integer | The id of the specific reservation e.g., 1 |
| register_timestamp | datetime | The datetime as an ISO format e.g., "2021-10-22T14:52:14.933Z" |
| name | string | The name of the user e.g., "Peter" |
| surname | string | The surname of the user e.g., "Parker" |
| birth_date | date | required | The birthdate of the user e.g., "2001-08-21" |
| citizen_id | string | The citizen id of the user (13 digits) e.g., "1134506547512" |
| occupation | string | The occupation of the user e.g., "Doctor" |
| address | string | The address of the user e.g., "Bangkok" |

Possible errors:

| Error code | Description |
| ---------------------|-------------------------------------------------|
| 404 Not found | Send a request but no object was found.|

#### Update reservation from reservation's id

This endpoint lets you update a specific reservation using the reservation's id as a parameter. The user needs to be authorized.

A request to update the reservations with a specific id looks like this:

PUT https://flamxby.herokuapp.com/reservation/{reservation_id}

With the following parameter:

| Parameter | Description |
| ------------|-------------------------------------------------|
| reservation_id | The id of the specific reservation as an integer e.g., 1|

With the following request body:

| Field | Type | Description |
| ------------|--------|-------------------------------------------------|
| register_timestamp | datetime | The datetime as an ISO format e.g., "2021-10-22T14:52:14.933Z" |

The response is the updated reservation information with the information of the user that is the owner. A message saying "No reservation with this id" is returned if there are no reservations with the specific id.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
   "reservation_id":1,
   "register_timestamp":"2022-10-22T16:32:46.144000",
   "owner":{
      "name":"pitchapa",
      "surname":"sae-lim",
      "birth_date":"2001-05-18",
      "citizen_id":"1818181818181",
      "occupation":"engineer",
      "address":"heaven"
   }
}

Where a Reservation Object is:

| Field | Type | Description |
| ------------|--------|-------------------------------------------------|
| reservation_id | integer | The id of the specific reservation e.g., 1 |
| register_timestamp | datetime | The datetime as an ISO format e.g., "2021-10-22T14:52:14.933Z" |
| name | string | The name of the user e.g., "Peter" |
| surname | string | The surname of the user e.g., "Parker" |
| birth_date | date | required | The birthdate of the user e.g., "2001-08-21" |
| citizen_id | string | The citizen id of the user (13 digits) e.g., "1134506547512" |
| occupation | string | The occupation of the user e.g., "Doctor" |
| address | string | The address of the user e.g., "Bangkok" |

Possible errors:

| Error code | Description |
| ---------------------|-------------------------------------------------|
| 401 Unauthorized |Send a request but not authenticated.|
| 404 Not found | Send a request but no object was found.|
| 422 Unprocessable Entity| Validation Error |

#### Delete reservation from reservation's id

This endpoint lets you delete a specific reservation using the reservation's id as a parameter. The user needs to be authorized.

A request to delete the reservations with a specific id looks like this:

DELETE https://flamxby.herokuapp.com/reservation/{reservation_id}

The response is a message saying "Delete successfully". A message saying "No reservation with this id" is returned if there are no reservations with the specific id.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

"Delete Successfully"

#### Get reservation from specific date

This endpoint lets you get a list of reservations using the year, month, and day as a parameter.

A request to fetch the list of reservations using year month, and day looks like this:

GET https://flamxby.herokuapp.com/reservation/{year}/{month}/{day}

With the following parameter:

| Parameter | Description |
| ------------|-------------------------------------------------|
| year | The year of the specific reservation as an integer e.g., 2020|
| month | The month of the specific reservation as an integer e.g., 10|
| day | The day of the specific reservation as an integer e.g., 21|

The response is the list of reservations information with the information of the user that is the owner. An empty list is returned if there are no reservations with the specific year, month, and day.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
   {
      "reservation_id":1,
      "register_timestamp":"2023-10-22T16:32:46.144000",
      "owner":{
         "name":"pitchapa",
         "surname":"sae-lim",
         "birth_date":"2001-05-18",
         "citizen_id":"1818181818181",
         "occupation":"engineer",
         "address":"heaven"
      }
   }
]

Where a Reservation Object is:

| Field | Type | Description |
| ------------|--------|-------------------------------------------------|
| reservation_id | integer | The id of the specific reservation e.g., 1 |
| register_timestamp | datetime | The datetime as an ISO format e.g., "2021-10-22T14:52:14.933Z" |
| name | string | The name of the user e.g., "Peter" |
| surname | string | The surname of the user e.g., "Parker" |
| birth_date | date | required | The birthdate of the user e.g., "2001-08-21" |
| citizen_id | string | The citizen id of the user (13 digits) e.g., "1134506547512" |
| occupation | string | The occupation of the user e.g., "Doctor" |
| address | string | The address of the user e.g., "Bangkok" |

Possible errors:

| Error code | Description |
| ---------------------|-------------------------------------------------|
| 422 Unprocessable Entity| Validation Error |