From b4fe998575e167a57f4f73f57f28797736757f60 Mon Sep 17 00:00:00 2001 From: rui hildt Date: Thu, 30 Apr 2020 11:55:21 +0200 Subject: [PATCH] Update endpoints status code and responses --- api-documentation.md | 240 ++++++++++++++++++++++++++----------------- 1 file changed, 146 insertions(+), 94 deletions(-) diff --git a/api-documentation.md b/api-documentation.md index 3406fee..041968d 100644 --- a/api-documentation.md +++ b/api-documentation.md @@ -1,23 +1,28 @@ ## API Documentation -___ + +--- + > Values required in **`bold`**. -### **Accounts** | `account` -| field | data type | metadata | -| :-------------| :---------------- | :-------------------------- | -| id | unsigned integer | primary key, auto-increment | -| username | varchar | required | -| email | varchar | required | -| password | varchar | required | -| timezone | varchar | | -| earliest_time | varchar | | -| latest_time | varchar | | -| created_at | datetime | generated by database | +### **Accounts** | `account` + +| field | data type | metadata | +| :------------ | :--------------- | :-------------------------- | +| id | unsigned integer | primary key, auto-increment | +| username | varchar | required | +| email | varchar | required | +| password | varchar | required | +| timezone | varchar | | +| earliest_time | varchar | | +| latest_time | varchar | | +| created_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`. ``` @@ -31,12 +36,12 @@ A json object for the account to register with **`username`**, **`email`**, **`p } ``` -##### Response +##### Response `201` + A json object for the registered account with `id`, `username`, `email`, `timezone`, `earliest_time` and `latest_time`. ``` { - "status": 201, "data": { "id": 1, "username": "jean", @@ -49,9 +54,11 @@ A json object for the registered account with `id`, `username`, `email`, `timezo ``` #### Log in an account + **`POST /api/accounts/login`** ##### Request + A json object for the account to login with either **`email`** or **`username`**, and **`password`** . ``` @@ -61,12 +68,12 @@ A json object for the account to login with either **`email`** or **`username`** } ``` -##### Response +##### Response `201` + A json object for the registered account with `id`, `username`, `email`, `timezone`, `earliest_time` and `latest_time`. ``` { - "status": 201, "data": { "id": 1, "username": "jean", @@ -79,9 +86,11 @@ A json object for the registered account with `id`, `username`, `email`, `timezo ``` #### 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`. ``` @@ -92,12 +101,12 @@ A json object for the account to register with `id` and any of `username`, `emai } ``` -##### Response +##### Response `200` + A json object for the registered account with `id`, `username`, `email`, `timezone`, `earliest_time` and `latest_time`. ``` { - "status": 200, "data": { "id": 1, "username": "jean", @@ -110,9 +119,11 @@ A json object for the registered account with `id`, `username`, `email`, `timezo ``` #### Delete an account + **`DELETE /api/accounts/:id`** ##### Request + A json object for the account to delete with `id`. ``` @@ -121,13 +132,12 @@ A json object for the account to delete with `id`. } ``` -##### Response -A json object for the deleted account with status code, message, `id`, `username` and `email`. +##### Response `200` + +A json object for the deleted account with `id`, `username` and `email`. ``` { - "status": 200, - "message": " '`username`' account with email '`email`' has been successfully deleted." "data": { "id": 15, "username": "jean", @@ -137,9 +147,11 @@ A json object for the deleted account with status code, message, `id`, `username ``` #### Get a list of meetings for an account + **`GET /api/accounts/:account_id/meetings`** ##### Request + A json object with an `account_id`. ``` @@ -148,14 +160,14 @@ A json object with an `account_id`. } ``` -##### Response +##### Response `200` + A json object for the specified account with an array of `meeting`. ``` { - "status": 200, "data": [{ - "id": "worldwide-strategy-meeting-for-11059", + "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", @@ -173,28 +185,31 @@ A json object for the specified account with an array of `meeting`. } ``` -### **Meetings** | `meeting` -| field | data type | metadata | -| :---------- | :-------- | :-------------------------------------------------------------------------------- | -| id | varchar | primary key, first 30 chars of `title` with words separated by `-` + 5 random int | -| title | varchar | required | -| description | varchar | | -| start_time | datetime | | -| timezone | varchar | | -| duration | int | required | -| status | boolean | required: `0` (proposed) or `1` (confirmed) | -| password | varchar | | -| created_at | datetime | generated by database | +### **Meetings** | `meeting` + +| field | data type | metadata | +| :---------- | :-------- | :------------------------------------------ | +| id | uuid | primary key, auto-generated | +| title | varchar | required | +| description | varchar | | +| start_time | datetime | | +| timezone | varchar | | +| duration | int | required | +| status | boolean | required: `0` (proposed) or `1` (confirmed) | +| password | varchar | | +| created_at | datetime | generated by database | #### Add a meeting + **`POST /api/meetings`** ##### Request + A json object for the meeting to add with **`id`**, **`title`**, `description`, `start_time`, **`duration`** and `password`. ``` { - "id": "worldwide-strategy-meeting-for-11059", + "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.", "duration": 90, @@ -202,14 +217,14 @@ A json object for the meeting to add with **`id`**, **`title`**, `description`, } ``` -##### Response +##### Response `201` + A json object for the added meeting with `id`, `title`, `description`, `start_time`, `duration`, `status` and `password`. ``` { - "status": 201, "data": { - "id": "worldwide-strategy-meeting-for-11059", + "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.", "duration": 90, @@ -219,14 +234,16 @@ A json object for the added meeting with `id`, `title`, `description`, `start_ti ``` #### Update a meeting + **`PUT /api/meetings/:id`** ##### Request + A json object for the meeting to update with `id`, `acount_id` and any of `title`, `description`, `start_time`, `timezone`, `duration`, `status` and `password`. ``` { - "id": "worldwide-strategy-meeting-for-11059", + "id": "f86983db-955e-43b8-be3e-bc92bbeb9b43", "account_id": 5, "start_time": "2022-02-16 20:00:00", "timezone": "Europe/Brussels", @@ -234,14 +251,14 @@ A json object for the meeting to update with `id`, `acount_id` and any of `title } ``` -##### Response +##### Response `200` + A json object for the updated meeting with `id`, `title`, `description`, `start_time`, `timezone`, `duration` and `status`. ``` { - "status": 200, "data": { - "id": "worldwide-strategy-meeting-for-11059", + "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", @@ -253,51 +270,56 @@ A json object for the updated meeting with `id`, `title`, `description`, `start_ ``` #### Delete a meeting + **`DELETE /api/meetings/:id`** ##### Request -A json object for the meeting to delete with `id` and `account_id`. + +A json object for the meeting to delete with `id`. ``` { - "id": "worldwide-strategy-meeting-for-11059", - "account_id": 5 + "id": "f86983db-955e-43b8-be3e-bc92bbeb9b43", } ``` -##### Response -A json object for the deleted meeting with status code and message. +##### Response `200` + +A json object for the deleted meeting with `id` and `meeting_title`. ``` { - "status": 200, - "message": "Meeting '`meeting_title`' has been successfully deleted." + "data": { + "id": "f86983db-955e-43b8-be3e-bc92bbeb9b43", + "meeting_title": "Worldwide strategy meeting for growth" + } } ``` -#### Get a list of all participants for a meeting +#### Get a list of all participants for a meeting + **`GET /api/meetings/:id/participants`** ##### Request -A json object with an `account_id`. + +A json object with a `meeting_id`. ``` { - "id": "worldwide-strategy-meeting-for-11059", - "account_id": 5 + "id": "f86983db-955e-43b8-be3e-bc92bbeb9b43" } ``` -##### Response +##### Response `200` + A json object for the specified meeting with an array of `participant`. ``` { - "status": 200, "data": [{ "id": 23, "account_id": 5, - "meeting_id": "worldwide-strategy-meeting-for-11059", + "meeting_id": "f86983db-955e-43b8-be3e-bc92bbeb9b43", "earliest_time": "09:30 AM", "latest_time": "05:00 PM", "quorum": 1, @@ -309,7 +331,7 @@ A json object for the specified meeting with an array of `participant`. { "id": 28, "account_id": 11, - "meeting_id": "worldwide-strategy-meeting-for-11059", + "meeting_id": "f86983db-955e-43b8-be3e-bc92bbeb9b43", "earliest_time": "10:00 AM", "latest_time": "09:00 PM", "quorum": 0, @@ -322,26 +344,28 @@ A json object for the specified meeting with an array of `participant`. } ``` -#### Get a list of complete availibility for a meeting +#### Get a list of complete availibility for a meeting + **`GET /api/meetings/:id/availibility`** ##### Request + A json object with a `meeting_id`. ``` { - "id": "worldwide-strategy-meeting-for-11059" + "id": "f86983db-955e-43b8-be3e-bc92bbeb9b43" } ``` -##### Response +##### Response `200` + A json object for the specified meeting with an array of `participant`. ``` { - "status": 200, "data": { - "meeting_id": "worldwide-strategy-meeting-for-11059", + "meeting_id": "f86983db-955e-43b8-be3e-bc92bbeb9b43", "availibility": [{ "participant_id": 5, "possible_date_id": 21, @@ -373,7 +397,8 @@ A json object for the specified meeting with an array of `participant`. } ``` -### **Possible Dates** | `possible_date` +### **Possible Dates** | `possible_date` + | field | data type | metadata | | :------------ | :-------- | :-------------------------- | | id | int | primary key, auto-increment | @@ -381,55 +406,64 @@ A json object for the specified meeting with an array of `participant`. | possible_date | date | foreign key, required | #### 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": "worldwide-strategy-meeting-for-11059", + "meeting_id": "f86983db-955e-43b8-be3e-bc92bbeb9b43", "possible_date": "2020-02-18" } ``` -##### Response +##### Response `201` + A json object for the added meeting with `id`, `meeting_id` and `possible_date`. ``` { - "status": 201, "data": { "id": 5, - "meeting_id": "worldwide-strategy-meeting-for-11059", + "meeting_id": "f86983db-955e-43b8-be3e-bc92bbeb9b43", "possible_date": "2020-02-18" } } ``` + #### Delete a possible date + **`DELETE /api/possible-dates/:id`** ##### Request -A json object for the possible date to delete with `id` and `account_id`. + +A json object for the possible date to delete with `id`. ``` { - "id": 12, - "account_id": 5 + "id": 12 } ``` -##### Response -A json object for the deleted possible date with status code and message. +##### Response `200` + +A json object for the deleted possible date with `id`, `meeting_id` and `possible_date`. ``` { - "status": 200, - "message": "Date '`possible_date`' has been successfully removed for the '`meeting_title`'." + "data": { + "id": 12, + "meeting_id": "f86983db-955e-43b8-be3e-bc92bbeb9b43", + "possible_date": "2020-02-18" + } } ``` -### **Participants** | `participant` +### **Participants** | `participant` + | field | data type | metadata | | :------------ | :-------- | :-------------------------- | | account_id | int | primary key, auto-increment | @@ -444,15 +478,17 @@ A json object for the deleted possible date with status code and message. | created_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": "worldwide-strategy-meeting-for-11059", + "meeting_id": "f86983db-955e-43b8-be3e-bc92bbeb9b43", "earliest_time": "08:30 AM", "latest_time": "08:00 PM", "quorum": 0, @@ -463,16 +499,16 @@ A json object for the participant to add with **`account_id`**, **`meeting_id`** } ``` -##### Response +##### Response `201` + A json object for the participant with `id`, `account_id`, `meeting_id`, `earliest_time`, `latest_time`, `quorum`, `mandatory`, `host`, `answered` and `timezone`. ``` { - "status": 201, "data": { "id": 23, "account_id": 5, - "meeting_id": "worldwide-strategy-meeting-for-11059", + "meeting_id": "f86983db-955e-43b8-be3e-bc92bbeb9b43", "earliest_time": "08:30 AM", "latest_time": "08:00 PM", "quorum": 0, @@ -485,9 +521,11 @@ A json object for the participant with `id`, `account_id`, `meeting_id`, `earlie ``` #### Update a participant + **`PUT /api/participants/:id`** ##### Request + A json object for the participant to invite with `id` and any of `id`, `earliest_time`, `latest_time`, `quorum`, `mandatory`, `host`, `answered` and `timezone`. ``` @@ -501,16 +539,16 @@ A json object for the participant to invite with `id` and any of `id`, `earliest } ``` -##### Response +##### Response `200` + A json object for the participant with `id`, `account_id`, `meeting_id`, `earliest_time`, `latest_time`, `quorum`, `mandatory`, `host`, `answered` and `timezone`. ``` { - "status": 200, "data": { "id": 23, "account_id": 5, - "meeting_id": "worldwide-strategy-meeting-for-11059", + "meeting_id": "f86983db-955e-43b8-be3e-bc92bbeb9b43", "earliest_time": "09:30 AM", "latest_time": "05:00 PM", "quorum": 1, @@ -523,9 +561,11 @@ A json object for the participant with `id`, `account_id`, `meeting_id`, `earlie ``` #### Delete a participant + **`DELETE /api/participants/:id`** ##### Request + A json object for the participant to delete with `id`. ``` @@ -535,16 +575,21 @@ A json object for the participant to delete with `id`. ``` ##### Response -A json object for the deleted participant with status code and message. + +A json object for the deleted participant with `participant_username`, `participant_username` and `meeting_title`. ``` { - "status": 200, - "message": "The '`participant_username`' has been successfully removed from the meeting '`meeting_title`'." + "data": { + "participant_username": "Sylvia", + "participant_email": "sylvia@email.com", + "meeting_title": "Worldwide strategy meeting for growth" + } } ``` -### **Availibility** | `availibility` +### **Availibility** | `availibility` + | field | data type | metadata | | :--------------- | :-------- | :--------------------------------- | | id | int | primary key, auto-increment | @@ -559,9 +604,11 @@ A json object for the deleted participant with status code and message. GET / DELETE / UPDATE #### Add an availibility for a possible date + **`POST /api/availibility`** ##### Request + A json object with the availibility to add with **`participant_id`**, **`possible_date_id`** and an array of intervals with **`preference`**, **`start_time`**, **`end_time`** and **`timezone`**. ``` @@ -585,12 +632,12 @@ A json object with the availibility to add with **`participant_id`**, **`possibl ``` -##### Response +##### Response `201` + A json object with the availibility to add with **`participant_id`**, **`possible_date_id`** and an array of intervals with **`id`**, **`preference`**, **`start_time`**, **`end_time`** and **`timezone`**. ``` { - "status": 201, "data": { "participant_id": 5, "possible_date_id": 21, @@ -614,9 +661,11 @@ A json object with the availibility to add with **`participant_id`**, **`possibl ``` #### Delete availibility for a possible date + **`DELETE /api/availibility/:id`** ##### Request + A json object for the availibility to delete with **`participant_id`** and **`possible_date_id`**. ``` @@ -626,12 +675,15 @@ A json object for the availibility to delete with **`participant_id`** and **`po } ``` -##### Response +##### Response `200` + A json object for the deleted availibility with status code and message. ``` { - "status": 200, - "message": "Availibility successfully deleted for `participant_username` on `possible_date`" + "data": { + "participant_username": "José", + "possible_date": "2020-05-12" + } } ```