documentation/api-documentation.md

693 lines
16 KiB
Markdown

## API Documentation
---
**URL** https://meeting-planner-backend.herokuapp.com/
---
> Values required in **`bold`**.
### **Accounts** | `account`
| field | data type | metadata |
| :------------ | :--------------- | :-------------------------- |
| id | unsigned integer | primary key, auto-increment |
| username | varchar | required |
| email | varchar | required, unique |
| password | varchar | required |
| timezone | varchar | |
| earliest_time | varchar | |
| latest_time | varchar | |
| created_at | datetime | generated by database |
| updated_at | datetime | generated by database |
#### Add an account
**`POST /api/accounts`**
##### Request
A json object for the account to register with **`username`**, **`email`**, **`password`**, `timezone`, `earliest_time` and `latest_time`.
```
{
"username": "jean",
"email": "jean@example.com",
"password": "really-strong-password",
"timezone": "Europe/Brussels",
"earliest_time":"09:30",
"latest_time":"22:00"
}
```
##### Response `201`
A json object for the registered account with `id`, `username`, `email`, `timezone`, `earliest_time` and `latest_time`.
```
{
"id": 1,
"username": "jean",
"email": "jean@example.com",
"timezone": "Europe/Brussels",
"earliest_time":"09:30",
"latest_time":"22:00"
}
```
#### Log in an account
**`POST /api/accounts/login`**
##### Request
A json object for the account to login with either **`email`** or **`username`**, and **`password`** .
```
{
"username": "jean",
"password": "super-strong-password"
}
```
##### Response `201`
A json object for the registered account with `id`, `username`, `email`, `timezone`, `earliest_time` and `latest_time`.
```
{
"id": 1,
"username": "jean",
"email": "jean@example.com",
"timezone": "Europe/Brussels",
"earliest_time":"09:30",
"latest_time":"22:00"l
}
```
#### Update an account
**`PUT /api/accounts/:id`**
##### Request
A json object for the account to register with `id` and any of `username`, `email`, `password`, `timezone`, `earliest_time`, `latest_time`.
```
{
"earliest_time": "08:30",
"latest_time": "20:00"
}
```
##### Response `200`
A json object for the registered account with `id`, `username`, `email`, `timezone`, `earliest_time` and `latest_time`.
```
{
"id": 1,
"username": "jean",
"email": "jean@example.com",
"timezone": "Europe/Brussels",
"earliest_time": "09:30",
"latest_time": "22:00"
}
```
#### Delete an account
**`DELETE /api/accounts/:id`**
##### Request
A json object for the account to delete with `token`.
```
{
"token": "dsdfs-sdfsf-fefzefz-fzef"
}
```
##### Response `200`
A json object for the deleted account with confirmation message.
```
{
"message": "Account with id 15 successfully deleted."
}
```
#### Get a list of meetings for an account
**`GET /api/accounts/:id/meetings`**
##### Request
A json object with an `token`.
```
{
"token": "qsd-qsdqd-dfsdfsfsd-sdfsdfs"
}
```
##### Response `200`
A json object for the specified account with an array of `meeting`.
```
[
{
"id": "03ac7a10-316f-46e8-bb55-8611e7e5b31c",
"title": "Worldwide meeting I",
"description": "Let's find the best ethical growth hacking technics together. Yeah, fun.",
"start_time": "10:30:00",
"timezone": "Europe/Brussels",
"duration": 90,
"status": false
},
{
"id": "2e8f3748-ea5a-4d20-b9a8-683ac65f5634",
"title": "Worldwide meeting II",
"description": "Let's find the best ethical growth hacking technics together. Yeah, fun.",
"start_time": "08:00:00",
"timezone": "America/New_York",
"duration": 90,
"status": false
},
{
"id": "a8344a68-7961-4bff-bb3b-b288f3abcf1c",
"title": "Worldwide meeting III",
"description": "Let's find the best ethical growth hacking technics together. Yeah, fun.",
"start_time": "14:30:00",
"timezone": "Asia/Kolkata",
"duration": 90,
"status": false
}
]
```
### **Meetings** | `meeting`
| field | data type | metadata |
| :---------- | :-------- | :------------------------------------------ |
| id | uuid | primary key, auto-generated |
| title | varchar | required |
| description | varchar | |
| start_time | datetime | |
| timezone | varchar | required |
| duration | int | required |
| status | boolean | required: `0` (proposed) or `1` (confirmed) |
| password | varchar | |
| created_at | datetime | generated by database |
| updated_at | datetime | generated by database |
#### Add a meeting
**`POST /api/meetings`**
##### Request
A json object for the meeting to add with **`title`**, `description`, `start_time`, **`duration`** and `password`.
```
{
"title": "Worldwide strategy meeting for growth",
"description": "Let's find the best ethical growth hacking technics together. Yeah, fun.",
"start_time": "10:00",
"timezone": "Europe/Brussels",
"duration": 90,
"status": 0,
"password": "simple-meeting-password"
}
```
##### Response `201`
A json object for the added meeting with `id`, `title`, `description`, `start_time`, `duration`, `status` and `password`.
```
{
"id": "f86983db-955e-43b8-be3e-bc92bbeb9b43",
"title": "Worldwide strategy meeting for growth",
"description": "Let's find the best ethical growth hacking technics together. Yeah, fun.",
"start_time": "10:00",
"timezone": "Europe/Brussels",
"duration": 90,
"status": 0,
"password" "simple-meeting-password"
}
```
#### Update a meeting
**`PUT /api/meetings/:id`**
##### Request
A json object for the meeting to update with any of `title`, `description`, `start_time`, `timezone`, `duration`, `status` and `password`.
```
{
"start_time": "2022-02-16 20:00:00",
"timezone": "Europe/Brussels",
"status": 1
}
```
##### Response `200`
A json object for the updated meeting with `id`, `title`, `description`, `start_time`, `timezone`, `duration` and `status`.
```
{
"id": "f86983db-955e-43b8-be3e-bc92bbeb9b43",
"title": "Worldwide strategy meeting for growth",
"description": "Let's find the best ethical growth hacking technics together.Yeah, fun.",
"start_time": "2022-02-16 20:00:00",
"timezone": "Europe/Brussels",
"duration: 90,
"status": 1
}
```
#### Delete a meeting
**`DELETE /api/meetings/:id`**
##### Request
A json object for the meeting to delete with `id`.
```
{
"id": "f86983db-955e-43b8-be3e-bc92bbeb9b43",
}
```
##### Response `200`
A json object for the deleted meeting with `message`.
```
{
"message": "Meeting with id f86983db-955e-43b8-be3e-bc92bbeb9b43 was successfully deleted."
}
```
#### Get a list of all participants for a meeting
**`GET /api/meetings/:id/participants`**
##### Request
A json object with a `meeting_id`.
```
{
"id": "03ac7a10-316f-46e8-bb55-8611e7e5b31c"
}
```
##### Response `200`
A json object for the specified meeting with an array of `participant`.
```
[
{
"account_id": 1,
"meeting_id": "03ac7a10-316f-46e8-bb55-8611e7e5b31c",
"earliest_time": "09:30:00",
"latest_time": "22:00:00",
"quorum": false,
"mandatory": false,
"host": false,
"answered": false,
"timezone": "Europe/Brussels"
},
{
"account_id": 2,
"meeting_id": "03ac7a10-316f-46e8-bb55-8611e7e5b31c",
"earliest_time": "09:00:00",
"latest_time": "20:00:00",
"quorum": false,
"mandatory": false,
"host": false,
"answered": false,
"timezone": "America/New_York"
}
]
```
#### Get a list of all possible dates for a meeting
**`GET /api/meetings/:id/possible-dates`**
##### Request
A json object with a `meeting_id`.
```
{
"id": "f86983db-955e-43b8-be3e-bc92bbeb9b43"
}
```
##### Response `200`
A json object for the specified meeting with an array of `possible_date`.
```
[
{
"id": 12,
"meeting_id": "f86983db-955e-43b8-be3e-bc92bbeb9b43",
"possible_date": "2020-02-18"
},
{
"id": 13,
"meeting_id": "f86983db-955e-43b8-be3e-bc92bbeb9b43",
"possible_date": "2020-02-19"
},
{
"id": 14,
"meeting_id": "f86983db-955e-43b8-be3e-bc92bbeb9b43",
"possible_date": "2020-02-22"
}
]
```
#### Get a list of all availability for a meeting
**`GET /api/meetings/:id/availability`**
##### Request
A json object with a `meeting_id`.
```
{
"id": "f86983db-955e-43b8-be3e-bc92bbeb9b43"
}
```
##### Response `200`
A json object for the specified meeting with `meeting_id` and an array of `availability`.
```
[
{
"id": 1,
"meeting_id": "03ac7a10-316f-46e8-bb55-8611e7e5b31c",
"account_id": 1,
"possible_date_id": 1,
"preference": false,
"start_time": "09:00:00",
"end_time": "22:00:00",
"timezone": "Europe/Brussels"
},
{
"id": 2,
"meeting_id": "03ac7a10-316f-46e8-bb55-8611e7e5b31c",
"account_id": 2,
"possible_date_id": 1,
"preference": false,
"start_time": "10:00:00",
"end_time": "20:00:00",
"timezone": "America/New_York"
},
{
"id": 3,
"meeting_id": "03ac7a10-316f-46e8-bb55-8611e7e5b31c",
"account_id": 1,
"possible_date_id": 2,
"preference": false,
"start_time": "10:00:00",
"end_time": "14:00:00",
"timezone": "Europe/Brussels"
}
]
```
### **Participants** | `participant`
| field | data type | metadata |
| :------------ | :-------- | :------------------------------------------- |
| account_id | varchar | required, foreign key, composite primary key |
| meeting_id | varchar | required, foreign key, composite primary key |
| earliest_time | datetime | |
| latest_time | datetime | |
| quorum | boolean | `0` (no) or `1` (yes) |
| mandatory | boolean | `0` (no) or `1` (yes) |
| host | boolean | `0` (no) or `1` (yes) |
| answered | boolean | `0` (no) or `1` (yes) |
| timezone | varchar | required |
| created_at | datetime | generated by database |
| updated_at | datetime | generated by database |
#### Invite a participant
**`POST /api/participants`**
##### Request
A json object for the participant to add with **`account_id`**, **`meeting_id`**, **`earliest_time`**, **`latest_time`**, **`quorum`**, **`mandatory`**, **`host`**, **`answered`** and **`timezone`**.
```
{
"account_id": 5,
"meeting_id": "f86983db-955e-43b8-be3e-bc92bbeb9b43",
"earliest_time": "08:30",
"latest_time": "20:00",
"quorum": 0,
"mandatory": 1,
"host": 0,
"answered": 0,
"timezone": "Europe/Brussels"
}
```
##### Response `201`
A json object for the participant with `id`, `account_id`, `meeting_id`, `earliest_time`, `latest_time`, `quorum`, `mandatory`, `host`, `answered` and `timezone`.
```
{
"account_id": 5,
"meeting_id": "f86983db-955e-43b8-be3e-bc92bbeb9b43",
"earliest_time": "08:30",
"latest_time": "20:00",
"quorum": 0,
"mandatory": 1,
"host": 0,
"answered": 0,
"timezone": "Europe/Brussels"
}
```
#### Update a participant
**`PUT /api/participants/:account_id-:meeting_id`**
##### Request
A json object for the participant to invite with any of `earliest_time`, `latest_time`, `quorum`, `mandatory`, `host`, `answered` and `timezone`.
```
{
"earliest_time": "09:30",
"latest_time": "17:00",
"quorum": 1,
"host": 1,
"answered": 1,
}
```
##### Response `200`
A json object for the participant with `account_id`, `meeting_id`, `earliest_time`, `latest_time`, `quorum`, `mandatory`, `host`, `answered` and `timezone`.
```
{
"account_id": 5,
"meeting_id": "f86983db-955e-43b8-be3e-bc92bbeb9b43",
"earliest_time": "09:30",
"latest_time": "17:00",
"quorum": 1,
"mandatory": 1,
"host": 1,
"answered": 1,
"timezone": "Europe/Brussels"
}
```
#### Delete a participant
**`DELETE /api/participants/:account_id-:meeting_id`**
##### Request
A json object for the participant to delete with `token`.
```
{
"token": "lknlkj-kjbkbj-kbjkbj-jkjh"
}
```
##### Response
A json object for the deleted participant with `message`.
```
{
"message": "Meeting with id 1-f86983db-955e-43b8-be3e-bc92bbeb9b43 was successfully deleted."
}
```
### **Possible Dates** | `possible_date`
| field | data type | metadata |
| :------------ | :-------- | :-------------------------- |
| id | int | primary key, auto-increment |
| meeting_id | varchar | foreign key, required |
| possible_date | date | required |
| created_at | datetime | generated by database |
| updated_at | datetime | generated by database |
#### Add a possible date
**`POST /api/possible-dates`**
##### Request
A json object for the meeting to add with **`meeting_id`** and **`possible_date`**.
```
{
"meeting_id": "03ac7a10-316f-46e8-bb55-8611e7e5b31c",
"possible_date": "2025-02-27"
}
```
##### Response `201`
A json object for the added meeting with `id`, `meeting_id` and `possible_date`.
```
{
"id": 20,
"meeting_id": "03ac7a10-316f-46e8-bb55-8611e7e5b31c",
"possible_date": "2025-02-26T23:00:00.000Z"
}
```
#### Delete a possible date
**`DELETE /api/possible-dates/:id`**
##### Request
A json object for the possible date to delete with `token`.
```
{
"token": "fsdfsdf-sdfsgdfg-dfgdfg-dfgd"
}
```
##### Response `200`
A json object for the deleted possible date with `message`.
```
{
"message": "Possible date with id 12 was successfully deleted."
}
```
### **Availability** | `availability`
| field | data type | metadata |
| :--------------- | :-------- | :-------------------------------------------- |
| id | int | primary key, auto-increment |
| account_id | int | foreign composite key (participant), required |
| meeting_id | uuid | foreign composite key (participant), required |
| possible_date_id | int | foreign key, required |
| preference | boolean | `0` (ideal) or `1` (yes), required |
| start_time | timestamp | required |
| end_time | timestamp | required |
| timezone | varchar | required |
| created_at | datetime | generated by database |
| updated_at | datetime | generated by database |
#### Add an availability
**`POST /api/availability`**
##### Request
A json object with the availability to add with **`participant_id`**, **`possible_date_id`** and an array of intervals with **`preference`**, **`start_time`**, **`end_time`** and **`timezone`**.
```
{
"meeting_id": "03ac7a10-316f-46e8-bb55-8611e7e5b31c",
"account_id": 1,
"possible_date_id": 1,
"preference": false,
"start_time": "23:00:00",
"end_time": "23:59:00",
"timezone": "Europe/Brussels"
}
```
##### Response `201`
A json object with the availability added with **`id`**, **`account_id`**, **`meeting_id`**, **`possible_date_id`** and an array of intervals with **`id`**, **`preference`**, **`start_time`**, **`end_time`** and **`timezone`**.
```
{
"id": 30,
"account_id": 1,
"meeting_id": "03ac7a10-316f-46e8-bb55-8611e7e5b31c",
"possible_date_id": 1,
"preference": false,
"start_time": "23:00:00",
"end_time": "23:59:00",
"timezone": "Europe/Brussels"
}
```
#### Delete an availability
**`DELETE /api/availability/:id`**
##### Request
A json object for the availability to delete with **`token`**.
```
{
"token": "bbeb9b43-fzefzef-zefdhffg-zgze"
}
```
##### Response `200`
A json object for the deleted availability with `message`.
```
{
"message": "Availability with id 30 was successfully deleted."
}
```