From db4bee8fa1e34bbfcd530451da9a4c048fd61b94 Mon Sep 17 00:00:00 2001 From: rui hildt Date: Fri, 28 Aug 2020 20:54:21 +0200 Subject: [PATCH] Fix doxumentation - update and fix examples - fix typos - streamline wording --- api-documentation.md | 298 +++++++++++++++---------------------------- database.dbml | 9 +- 2 files changed, 109 insertions(+), 198 deletions(-) diff --git a/api-documentation.md b/api-documentation.md index a787fdb..4433f92 100644 --- a/api-documentation.md +++ b/api-documentation.md @@ -47,12 +47,15 @@ A json object for the registered account with `id`, `username`, `email`, `timezo ``` { - "id": 1, - "username": "jean", - "email": "jean@example.com", - "timezone": "Europe/Brussels", - "earliest_time":"09:30", - "latest_time":"22:00" + "user": { + "id": 1, + "username": "jean", + "email": "jean@example.com", + "timezone": "Europe/Brussels", + "earliest_time":"09:30", + "latest_time":"22:00" + }, + "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1CJlbWFpbCI6ImphY2tAZXc2VybmFtZSI6ImphY2siLhhbXBsZS5jb20iLCJpYXQiOjE1OTg2MTc2MTksImV4cCI6MTYwMTIwOTYxOX0.s85ti_rzBVHJ6Gt1MY7seYfdcjB6sR939p2CexA40gI" } ``` @@ -62,27 +65,30 @@ A json object for the registered account with `id`, `username`, `email`, `timezo ##### Request -A json object for the account to login with either **`email`** or **`username`**, and **`password`** . +A json object for the account to login with either **`email`** and **`password`** . ``` { - "username": "jean", - "password": "super-strong-password" + "email": "jean@example.com", + "password": "password" } ``` ##### Response `201` -A json object for the registered account with `id`, `username`, `email`, `timezone`, `earliest_time` and `latest_time`. +A json object for the logged in account with `id`, `username`, `email`, `timezone`, `earliest_time`, `latest_time` and `token`. ``` { - "id": 1, - "username": "jean", - "email": "jean@example.com", - "timezone": "Europe/Brussels", - "earliest_time":"09:30", - "latest_time":"22:00"l + "user": { + "id": 1, + "username": "jean", + "email": "jean@example.com", + "timezone": "Europe/Brussels", + "earliest_time":"09:30", + "latest_time":"22:00" + }, + "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1CJlbWFpbCI6ImphY2tAZXc2VybmFtZSI6ImphY2siLhhbXBsZS5jb20iLCJpYXQiOjE1OTg2MTc2MTksImV4cCI6MTYwMTIwOTYxOX0.s85ti_rzBVHJ6Gt1MY7seYfdcjB6sR939p2CexA40gI" } ``` @@ -92,7 +98,7 @@ A json object for the registered account with `id`, `username`, `email`, `timezo ##### Request -A json object for the account to register with `id` and any of `username`, `email`, `password`, `timezone`, `earliest_time`, `latest_time`. +A json object for the account to update with any of `username`, `email`, `password`, `timezone`, `earliest_time`, `latest_time`. ``` { @@ -103,7 +109,7 @@ A json object for the account to register with `id` and any of `username`, `emai ##### Response `200` -A json object for the registered account with `id`, `username`, `email`, `timezone`, `earliest_time` and `latest_time`. +A json object for the updated account with `id`, `username`, `email`, `timezone`, `earliest_time` and `latest_time`. ``` { @@ -120,16 +126,6 @@ A json object for the registered account with `id`, `username`, `email`, `timezo **`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. @@ -144,16 +140,6 @@ A json object for the deleted account with confirmation message. **`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`. @@ -164,25 +150,25 @@ 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", + "start_time": "2025-05-05T10:30:00Z", "duration": 90, - "status": false + "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", + "start_time": "2025-05-05T08:00:00Z", "duration": 90, - "status": false + "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", + "start_time": "2025-05-05T14:30:00Z", "duration": 90, - "status": false + "status": "false" } ] @@ -195,7 +181,7 @@ A json object for the specified account with an array of `meeting`. | id | uuid | primary key, auto-generated | | title | string | required | | description | string | | -| start_time | datetime | | +| start_time | datetime | UTC Timestamp | | duration | int | required | | status | boolean | required: `0` (proposed) or `1` (confirmed) | | password | string | | @@ -214,10 +200,9 @@ A json object for the meeting to add with **`title`**, `description`, `start_tim { "title": "Worldwide strategy meeting for growth", "description": "Let's find the best ethical growth hacking technics together. Yeah, fun.", - "start_time": "10:00", + "start_time": "2025-05-05T10:00:00Z", "duration": 90, - "status": 0, - "password": "simple-meeting-password" + "status": 0 } ``` @@ -230,10 +215,9 @@ A json object for the added meeting with `id`, `title`, `description`, `start_ti "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", + "start_time": "2025-05-05T10:00:00Z", "duration": 90, - "status": 0, - "password" "simple-meeting-password" + "status": 0 } ``` @@ -247,7 +231,7 @@ A json object for the meeting to update with any of `title`, `description`, `sta ``` { - "start_time": "2022-02-16 20:00:00", + "start_time": "2025-05-05T10:00:00Z", "status": 1 } ``` @@ -261,7 +245,7 @@ A json object for the updated meeting with `id`, `title`, `description`, `start_ "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", + "start_time": "2025-05-05T10:00:00Z", "duration: 90, "status": 1 } @@ -271,16 +255,6 @@ A json object for the updated meeting with `id`, `title`, `description`, `start_ **`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`. @@ -295,16 +269,6 @@ A json object for the deleted meeting with `message`. **`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`. @@ -312,24 +276,24 @@ A json object for the specified meeting with an array of `participant`. ``` [ { + "id": "j8y9ta10-5g4f-46e8-bb55-8611e7e5bgtr", + "email": "liza@example.com", "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, + "quorum": "false", + "mandatory": "false", + "host": "false", + "answered": "false" }, { - "account_id": 2, + "id": "gh59ta10-5g4f-46e8-bb55-8611e7eftg8t", + "email": "toni@example.com", + "account_id": 23, "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, + "quorum": "false", + "mandatory": "false", + "host": "false", + "answered": "false" } ] @@ -339,16 +303,6 @@ A json object for the specified meeting with an array of `participant`. **`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`. @@ -377,48 +331,35 @@ A json object for the specified meeting with an array of `possible_date`. **`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`. +A json object for the specified meeting with an array of `availability`. ``` [ { "id": 1, - "meeting_id": "03ac7a10-316f-46e8-bb55-8611e7e5b31c", - "account_id": 1, + "participant_id": "gt537a10-316f-46e8-bb55-8611e7e5b31c", "possible_date_id": 1, "preference": false, - "start_time": "09:00", - "end_time": "22:00", + "start_time": "2025-05-05T09:00:00Z", + "end_time": "2025-05-05T22:00:00Z" }, { "id": 2, - "meeting_id": "03ac7a10-316f-46e8-bb55-8611e7e5b31c", - "account_id": 2, + "participant_id": "7a103ac0-316f-46e8-bb55-8611eb31c7e5", "possible_date_id": 1, "preference": false, - "start_time": "10:00:00", - "end_time": "20:00:00", + "start_time": "2025-05-06T10:00:00Z", + "end_time": "2025-05-06T20:00:00Z" }, { "id": 3, - "meeting_id": "03ac7a10-316f-46e8-bb55-8611e7e5b31c", - "account_id": 1, + "participant_id": "7a1003ac7a10-316f-46e8-bb55-8611e7e5b31c11e7e", "possible_date_id": 2, "preference": false, - "start_time": "10:00:00", - "end_time": "14:00:00", + "start_time": "2025-05-07T10:00:00Z", + "end_time": "2025-05-07T10:00:00Z" } ] @@ -426,16 +367,18 @@ A json object for the specified meeting with `meeting_id` and an array of `avail ### **Participants** | `participant` -| field | data type | metadata | -| :------------ | :-------- | :------------------------------------------- | -| account_id | string | required, foreign key, composite primary key | -| meeting_id | string | required, foreign key, composite primary key | -| quorum | boolean | `0` (no) or `1` (yes) | -| mandatory | boolean | `0` (no) or `1` (yes) | -| host | boolean | required, `0` (no) or `1` (yes) | -| answered | boolean | required, `0` (no) or `1` (yes) | -| created_at | datetime | generated by database | -| updated_at | datetime | generated by database | +| field | data type | metadata | +| :--------- | :-------- | :------------------------------ | +| id | uuid | required, primary key | +| email | string | | +| account_id | string | foreign key | +| meeting_id | string | required, foreign key | +| quorum | boolean | `0` (no) or `1` (yes) | +| mandatory | boolean | `0` (no) or `1` (yes) | +| host | boolean | required, `0` (no) or `1` (yes) | +| answered | boolean | required, `0` (no) or `1` (yes) | +| created_at | datetime | generated by database | +| updated_at | datetime | generated by database | #### Invite a participant @@ -443,78 +386,73 @@ A json object for the specified meeting with `meeting_id` and an array of `avail ##### Request -A json object for the participant to add with **`account_id`**, **`meeting_id`**, **`quorum`**, **`mandatory`**, **`host`** and **`answered`**. +A json object for the participant to add with `email`, `account_id`, **`meeting_id`**, `quorum`, `mandatory`, **`host`** and **`answered`**. ``` { + "email": "john@example.com", "account_id": 5, "meeting_id": "f86983db-955e-43b8-be3e-bc92bbeb9b43", "quorum": 0, "mandatory": 1, "host": 0, - "answered": 0, + "answered": 0 } ``` ##### Response `201` -A json object for the participant with `id`, `account_id`, `meeting_id`, `quorum`, `mandatory`, `host` and `answered`. +A json object for the added participant with `id`, `email`, `account_id`, `meeting_id`, `quorum`, `mandatory`, `host` and `answered`. ``` { + "id": "983dbf86-955e-43b8-be3e-b9b43bc92bbe", + "email": "john@example.com", "account_id": 5, "meeting_id": "f86983db-955e-43b8-be3e-bc92bbeb9b43", "quorum": 0, "mandatory": 1, "host": 0, - "answered": 0, + "answered": 0 } ``` #### Update a participant -**`PUT /api/participants/:account_id-:meeting_id`** +**`PUT /api/participants/:id`** ##### Request -A json object for the participant to invite with any of `quorum`, `mandatory`, `host` and `answered`. +A json object for the participant to update with any of `quorum`, `mandatory`, `host` and `answered`. ``` { "quorum": 1, "host": 1, - "answered": 1, + "answered": 1 } ``` ##### Response `200` -A json object for the participant with `account_id`, `meeting_id`, `quorum`, `mandatory`, `host` and `answered`. +A json object for the updated participant with `id`, `email`, `account_id`, `meeting_id`, `quorum`, `mandatory`, `host` and `answered`. ``` { + "id": "983dbf86-955e-43b8-be3e-b9b43bc92bbe", + "email": "john@example.com", "account_id": 5, "meeting_id": "f86983db-955e-43b8-be3e-bc92bbeb9b43", "quorum": 1, "mandatory": 1, "host": 1, - "answered": 1, + "answered": 1 } ``` #### 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" -} -``` +**`DELETE /api/participants/:id`** ##### Response @@ -522,7 +460,7 @@ A json object for the deleted participant with `message`. ``` { - "message": "Meeting with id 1-f86983db-955e-43b8-be3e-bc92bbeb9b43 was successfully deleted." + "message": "Participant with id 983dbf86-955e-43b8-be3e-b9b43bc92bbe was successfully deleted." } ``` @@ -567,16 +505,6 @@ A json object for the added meeting with `id`, `meeting_id` and `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`. @@ -589,17 +517,16 @@ A json object for the deleted possible date with `message`. ### **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 | datetime | required | -| end_time | datetime | required | -| created_at | datetime | generated by database | -| updated_at | datetime | generated by database | +| field | data type | metadata | +| :--------------- | :-------- | :--------------------------------- | +| id | int | primary key, auto-increment | +| participant_id | int | foreign, required | +| possible_date_id | int | foreign key, required | +| preference | boolean | `0` (ideal) or `1` (yes), required | +| start_time | datetime | required, UTC timestamp | +| end_time | datetime | required, UTC timestamp | +| created_at | datetime | generated by database | +| updated_at | datetime | generated by database | #### Add an availability @@ -607,33 +534,30 @@ A json object for the deleted possible date with `message`. ##### Request -A json object with the availability to add with **`participant_id`**, **`possible_date_id`** and an array of intervals with **`preference`**, **`start_time`** and **`end_time`**. +A json object with the availability to add with **`participant_id`**, **`possible_date_id`**, **`preference`**, **`start_time`** and **`end_time`**. ``` { - "meeting_id": "03ac7a10-316f-46e8-bb55-8611e7e5b31c", - "account_id": 1, + "participant_id": "03ac7a10-316f-46e8-bb55-8611e7e5b31c", "possible_date_id": 1, "preference": false, - "start_time": "23:00:00", - "end_time": "23:59:00", + "start_time": "2025-05-05T10:00:00Z", + "end_time": "2025-05-05T20:00:00Z" } - ``` ##### 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`** and **`end_time`**. +A json object with the availability added with `id`, `participant_id`, `possible_date_id`, `preference`, `start_time` and `end_time`. ``` { "id": 30, - "account_id": 1, - "meeting_id": "03ac7a10-316f-46e8-bb55-8611e7e5b31c", + "participant_id": "03ac7a10-316f-46e8-bb55-8611e7e5b31c", "possible_date_id": 1, "preference": false, - "start_time": "23:00:00", - "end_time": "23:59:00", + "start_time": "2025-05-05T10:00:00Z", + "end_time": "2025-05-05T20:00:00Z" } ``` @@ -641,16 +565,6 @@ A json object with the availability added with **`id`**, **`account_id`**, **`me **`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`. diff --git a/database.dbml b/database.dbml index e8888d0..969bf13 100644 --- a/database.dbml +++ b/database.dbml @@ -30,6 +30,8 @@ Table meeting as M { } Table participant as P { + id uuid [pk, unique] + email string account_id int [ref: > A.id] meeting_id uuid [ref: > M.id] quorum boolean @@ -38,10 +40,6 @@ Table participant as P { answered boolean created_at datetime [default: `now()`] updated_at datetime [default: `now()`] - - indexes { - (account_id, meeting_id) [pk] // composite primary key - } } Table possible_date as D { @@ -53,8 +51,7 @@ Table possible_date as D { Table availability { id int [pk, increment, unique] - account_id participant_id [ref: > P.account_id] - meeting_id participant_id [ref: > P.meeting_id] + participant_id string [ref: > P.id] possible_date_id int [ref: > D.id] preference availability_preference start_time datetime