From 94f9b59f12ad5917a78fe4a745521db4837e9323 Mon Sep 17 00:00:00 2001 From: Hamza Ali Date: Fri, 1 Nov 2019 09:31:58 +0700 Subject: [PATCH] docs: add websocket specification. --- WEBSOCKET.md | 348 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 348 insertions(+) create mode 100644 WEBSOCKET.md diff --git a/WEBSOCKET.md b/WEBSOCKET.md new file mode 100644 index 0000000..7b3ba2a --- /dev/null +++ b/WEBSOCKET.md @@ -0,0 +1,348 @@ +# Websocket Protocol Documentation + +## Table of contents + +- [Staff Endpoints](#staff-endpoints) + - [Server To Staff](#server-to-staff) + - [claimed](#claimed) + - [new](#new) + - [taken](#taken) + - [Staff to Server](#staff-to-server) + - [accept](#accept) + - [cancel](#cancel) + - [complete](#complete) + - [pick](#pick) + - [unpick](#unpick) +- [Kiosk Endpoints](#kiosk-endpoints) + - [Kiosk to Server](#kiosk-to-server) + - [new](#new-1) + - [query](#query) +- [Display Endpoints](#display-endpoints) + - [Server to Display](#server-to-display) + - [cancel](#cancel-1) + - [claimed](#claimed-1) + - [complete](#complete-1) + - [pick](#pick-1) + - [unpick](#unpick-1) + +## Staff Endpoints + +These endpoints are just going to be used between a staff member handling clients and the server. + +### Server to Staff + +#### claimed + +This message is sent to the staff when another staff member has already claimed a ticket. +This message serves the function of letting staff members know when a ticket is no longer +needing a staff member to claim it. + +##### example: + +``` +claimed {"id":0,"email":"example@example.com","name":"Example Name","staff":"StaffMember","start":"2019-10-01T04:12:19Z","end":"1970-01-01T00:00:00Z"} +``` + +This example message would tell the staff member that the ticket was claimed by 'StaffMember'. + +#### new + +This message is sent to the staff when a kiosk creates a new ticket. + +##### example: + +``` +new {"id":0,"email":"example@example.com","name":"Example Name","staff":"{}","start":"2019-10-01T04:12:19Z","end":"1970-01-01T00:00:00Z"} +``` + +This example message would tell the staff member that a client by the name of 'Example Name' has created a new ticket. + +#### taken + +This message is sent to staff members when they haven't picked an assigned table yet. +The purpose of the message is to allow staff members know what tables are available to pick. + +#### example: + +``` +taken 0 3 5 +``` + +This sample message would tell the staff member that table 0, 3, and 5 are already taken and are not available. + +### Staff to Server + +#### accept + +This message is sent from the staff member when they want to claim a ticket. + +##### example + +``` +accept 0 +``` + +This sample message would claim a ticket with the ID of 0 + +##### responses: + +###### error accept your session token was found to be invalid. please relogin + +This means that the internal token used to identify you was deamed incorrect or invalid. You must relog + +###### error accept you do not have a table chosen + +You must be assigned to a table before handling tickets. + +###### error accept ticket id does not exist + +The ticket with the provided id you are trying to accept does not exist. + +###### error accept this ticket is now claimed + +The ticket you are trying to claim has already been claimed by another user. + +###### error accept the ticket has already been completed or cancelled + +This means that when the ticket you are trying to accept is already claimed by someone else + +###### success claimed `{id}` + +The staff member has successfully claimed the ticket. + +#### cancel + +This message is sent from the staff member when a client decided to cancel a ticket, or does not show up. + +##### example: + +``` +cancel 0 +``` + +This example message would cancel the ticket with the id of 0 + +##### responses: + +###### error cancel you are not assigned to any table + +You must be assigned to a table before handling tickets. + +###### error cancel ticket id does not exist + +The ticket with the provided id you are trying to cancel does not exist. + +###### error cancel you do not own this ticket + +The ticket you are trying to cancel must be owned by you. + +###### error cancel the ticket has already been completed or cancelled + +This means the ticket you are trying to cancel cannot be cancelled +as it has already previously been, or has been completed. + +###### success cancel `{id}` + +The ticket was successfully cancelled with no issues. + + +#### complete + +This message is sent from the staff member when a staff member completes a ticket + +##### example: + +``` +complete 0 +``` + +This example message would complete the ticket with the id of 0 + +##### responses: + +###### error complete you are not assigned to any table + +You must be assigned to a table before handling tickets. + +###### error complete ticket id does not exist + +The ticket with the provided id you are trying to complete does not exist. + +###### error complete you do not own this ticket + +The ticket you are trying to complete must be owned by you. + +###### error complete the ticket has already been completed or cancelled + +This means the ticket you are trying to cancel cannot be cancelled +as it has already previously been, or has been completed. + +###### success complete `{id}` + +The ticket was successfully completed with no issues. + +#### pick + +This command lets a staff member pick a table + +##### example: + +``` +pick 0 abcdefghijklmnoprstuvwxy +``` + +This command would assign the client the table 0, and validate their identity with their token + +##### responses: + +###### error pick the provided token does not belong to any staff member + +You are using an invalid token. Try to relog + +###### error the chosen table is not available + +This means that the table you are chosing (0, in this case) is already taken, +or you are picking an invalid number. + +###### success pick `{table}` + +You successfully claimed the table and can start accepting tickets + +#### unpick + +This command lets a staff member unset their chosen table + +##### example: + +``` +unpick +``` + +This would unassign the table the client has chosen + +##### responses: + +###### error unpick you do not have a table assigned + +This means you do not have a current table you have picked + +###### success unpick + +This means you have successfully reset your chosen table + +## Kiosk Endpoints + +These endpoints are used between the kiosk (client-facing machine), and the server + +### Kiosk to Server + +#### new + +This message is sent from the kiosk when a new ticket is requested to be created + +##### example: + +``` +new example@example.com Example Name +``` + +This sample command will create a new ticket under the email of +example@example.com, and their name Example Name + +##### responses: + +###### success new `{jsonEncodedTicket}` + +The ticket was successfully created for the client + +#### query + +This message is sent from the kiosk when the kiosk tries to autocomplete the client's name + +##### example: + +``` +query example@example.com +``` + +This sample command will try to find the name for the client +who's email is example@example.com + +##### responses: + +###### error query visitor email does not exist + +The email you are trying to query has no corresponding user, +this is the first time that user is visiting + +###### success query `{name}` + +This message returns the corresponding name that was found +in our database for the example proivded. + +## Display Endpoints + +These endpoints will be used by the display machine + +### Server to Display + +#### cancel + +This command will tell the display to clear the table's ticket + +##### example: + +``` +cancel 0 +``` + +This will cancel the ticket that was planned to happen on table 0 + +#### claimed + +This command will tell the display that a ticket was claimed by a staff memeber + +##### example: + +``` +claimed StaffMember 0 {"id":0,"email":"example@example.com","name":"Example Name","staff":"StaffMember","start":"2019-10-01T04:12:19Z","end":"1970-01-01T00:00:00Z"} +``` + +This will tell the display that the staff member 'StaffMember' has claimed the ticket on table 0 + +#### complete + +This tells the display that the ticket on a table has been successfully completed + +##### example: + +``` +complete 0 +``` + +This tells the display that the ticket on table 0 has been completed + +#### pick + +This tells the display that a table has been claimed by a staff member +and to show it as online on the display + +##### example: + +``` +pick 0 +``` + +This tells the display that the table 0 has been picked by a staff member + +#### unpick + +This tells the display that a client has left serving on a table + +##### example: + +``` +unpick 0 +``` + +This tells the display that the table 0 is no longer going to be accepting/serving tickets. \ No newline at end of file