Differences

This shows you the differences between two versions of the page.

--- api-workplace-fabric [2018/07/05 11:17]
hari
+++ api-workplace-fabric [2018/07/17 11:04] (current)
hari [Server to client data stream]
@@ Line 310: / Line 310: @@
 API call
 <code>
-GET https://apiserver/freespace/users/uuid-user-id-of-user
+GET https://apiserver/freespace/users/me
 </code>
@@ Line 323: / Line 323: @@
   - The server examines the token. If no token is passed, then a 401 is returned.
-  - Next, the server finds the user who owns the token. If that user's ID and the ID specified in the URL do not match, then a 403 is returned.
   - The server fetches the profile from the database based on the user ID.
   - The server returns the profile along with a 200.
@@ Line 338: / Line 337: @@
 <code>
 {
+  "id": "melania's-uuid-user-id"
   "name": "Melania Carmella",
   "email": "m.carmella@ramseytech.co.uk",
   "phone": "+44 20 7946 0292",
   "city": {
-    "id": "45fed8b2-8016-11e8-b6f0-334f2875887b",
+    "id": "uuid-based-city-id-for-london",
     "name": "London"
   },
   "preferredBuilding": {
-    "id": "60a935c2-8016-11e8-866a-dbc0c4481511",
+    "id": "uuid-based-building-id-for-high-holborn",
     "name": "High Holborn"
   },
   "preferredFloor": {
-    "id": "ad8b56e0-8016-11e8-a81a-13db06616260",
+    "id": "uuid-based-floor-id-for-first-floor-of-high-holborn",
     "name": "1st"
   },
   "preferredDepartment": {
-    "id": "c9985f90-8016-11e8-88f4-e3c3676aed2e",
+    "id": "uuid-based-dept-id-for-r&d-1st-floor-high-holborn",
     "name": "Research and Development"
   }
@@ Line 360: / Line 360: @@
 </code>
+==== Response if token is missing or invalid ====
+Headers
+<code>
+HTTP/1.1 401 INVALID-TOKEN
+</code>
+Body: none
+==== Response if some other error / exception occurs ====
+Headers
+<code>
+HTTP/1.1 500 ERROR
+Content-Type: text/plain
+</code>
+Body
+<code>
+This is a sample error message.
+</code>
+===== Get space hierarchy =====
+==== Request ====
+API call
+<code>
+GET https://apiserver/freespace/cities/<city-id>/spaces
+</code>
+Headers
+<code>
+Authorization: Bearer access-token-for-the-user
+</code>
+==== What the server does between request and response ====
+  - The server checks for the validity of the access token. If the token is not found in the server's records, then a 401 is returned.
+  - The server checks if the city ID exists in the server's records. If not so, then a 404 is returned.
+  - The server checks for buildings in the city. If none exist, a 204 is returned.
+  - The server fetches the buildings, floors, departments and space availability in each floor. All the data is combined into a hierarchy and returned along with a 200 response.
+  - If there are errors at any stage, a 500 is returned.
+==== Response if the request is successful ====
+Headers
+<code>
+HTTP/1.1 200 OK
+Content-Type: application/json
+</code>
+Body:
+<code>
+[
+  {
+    "id": "uuid-of-the-building",
+    "name": "Willis Towers",
+    "address": "22, Lewis Street, London",
+    "floors": [
+      {
+        "id": "uuid-of-the-floor",
+        "name": "1st",
+        "spaces": [
+          {
+            "id": "uuid-of-the-space",
+            "name": "Task desk",
+            "available": 32
+          },
+          ... more spaces..
+        ]
+      },
+      ... more floors ...
+    ]
+  },
+  ... more buildings ...
+]
+</code>
+==== Response if the token is invalid ====
+Header
+<code>
+HTTP/1.1 401 INVALID-TOKEN
+</code>
+Body: none
+==== Response if the city ID does not exist ====
+Header
+<code>
+HTTP/1.1 404 CITY-NOT-FOUND
+</code>
+Body: none
+==== Response if there are no buildings in the city ====
+Header
+<code>
+HTTP/1.1 204 NONE
+</code>
+Body: none
+==== Response for other errors / exceptions ====
+Header
+<code>
+HTTP/1.1 500 ERROR
+Content-Type: text/plain
+</code>
+Body
+<code>
+This is a sample error message.
+</code>
+===== Get floor map =====
+==== Request ====
+API call
+<code>
+GET https://apiserver/freespace/buildings/uuid-for-building/floors/uuid-for-floor/floor-map
+</code>
+Headers
+<code>
+Authorization: Bearer access-token-of-user
+</code>
+==== What the server does between request and response ====
+  - The server checks if the access token is that of a valid user. If not so, a 401 is returned.
+  - The server then fetches the floor based on building ID and floor ID. If not found, a 404 is returned.
+  - The server fetches the following from the database
+    - The image of the floor's schematic
+    - List of departments and their central co-ordinate
+    - List of working spaces: their type, X co-ordinate and Y co-ordinate
+  - The above is returned with a 200 status.
+  - If there is an error at any point, a 500 is returned.
+==== Response if the request is successful ====
+Headers
+<code>
+HTTP/1.1 200 OK
+Content-Type: application/json
+</code>
+Body
+<code>
+{
+  "id": "uuid-of-the-floor",
+  "schematic": "https://path/to/schematic/diagram/image.png-or-jpg",
+  "departments": [
+    {
+      "id": "uuid-of-the-department",
+      "name": "Information Technology",
+      "x": X co-ordinate of the centre of the department,
+      "y": Y co-ordinate of the centre of the department,
+    },
+    ... more departments ...
+  ],
+  "spaces": [
+    {
+      "id": "uuid-of-the-individual-space",
+      "categoryId": "uuid-of-the-space-category",
+      "x": X co-ordinate of the workspace,
+      "y": Y co-ordinate of the workspace,
+    }
+    ... more spaces ...
+  ]
+}
+</code>
+==== Response if access token is invalid ====
+Headers
+<code>
+HTTP/1.1 401 INVALID-TOKEN
+</code>
+Body: none
+==== Response if building is not found ====
+Headers
+<code>
+HTTP/1.1 404 BUILDING-NOT-FOUND
+</code>
+Body: none
+==== Response if floor is not found ====
+Headers
+<code>
+HTTP/1.1 404 FLOOR-NOT-FOUND
+</code>
+Body: none
+==== Response for any other error / exception ====
+Headers
+<code>
+HTTP/1.1 500 ERROR
+Content-Type: text/plain
+</code>
+Body
+<code>
+This is a sample error message.
+</code>
+===== Update user profile =====
+==== Request ====
+API call
+<code>
+PATCH https://apiserver/freespace/users/me
+</code>
+Headers
+<code>
+Authorization: Bearer <access-token-for-melania>
+Content-Type: application/json
+</code>
+Body
+<code>
+{
+  "phone": "phone-number",
+  "city": "city-uuid-of-executive's-city",
+  "preferredBuildingId": "uuid-of-preferred-building",
+  "preferredFloor": "uuid-of-preferredFloor",
+  "preferredDepartment": "uuid-of-preferred-department"
+}
+</code>
+==== What the server does between request and response ====
+  - The server checks if the access token is valid for the requesting user. If it's not, then 401 is returned.
+  - A 404 is returned if any of the requested city, building, floor or department are not found.
+  - Next, the server updates the changes in profile in the record in database. A 204 is returned.
+  - If there are errors / exceptions on the way, 500 is returned.
+==== Response if the updation is successful ====
+Headers
+<code>
+HTTP/1.1 204 DONE
+</code>
+Body: none
+==== Response if access token is invalid ====
+Headers
+<code>
+HTTP/1.1 401 INVALID-TOKEN
+</code>
+Body: none
+==== Response if city / building / floor / department does not exist ====
+Headers
+<code>
+HTTP/1.1 404 CITY-NOT-FOUND
+or
+HTTP/1.1 404 BUILDING-NOT-FOUND
+or
+HTTP/1.1 404 FLOOR-NOT-FOUND
+or
+HTTP/1.1 404 DEPARTMENT-NOT-FOUND
+</code>
+Body: none
+==== Response for some other error / exception ====
+Headers
+<code>
+HTTP/1.1 500 ERROR
+</code>
+Body
+<code>
+This is a sample error message.
+</code>
+===== Log out =====
+==== Request ====
+API call
+<code>
+POST https://apiserver/freespace/oauth/revoke
+</code>
+Headers
+<code>
+Authorization: Bearer access-token-for-melania
+</code>
+Body: none
+==== What the server does between request and response ====
+The server looks up the bearer token in the database and deletes it, so that the token is invalid from the next time and the user is always redirected to the login page. The response always leads to a 204 response.
+==== Response ====
+Headers
+<code>
+HTTP/1.1 204 DONE
+</code>
+===== Live occupancy update =====
+==== Connection ====
+URL
+<code>
+ws://apiserver:8000/live-occupancy
+</code>
+==== Client to server data stream ====
+None
+==== Server to client data stream ====
+<code>
+{
+  "spaceId": "uuid-of-the-room/space-that-is-occupied-or-released",
+  "departmentId": "uuid-of-the-department-where-the-space-is",
+  "floorId": "uuid-of-the-floor-where-the-space-is",
+  "buildingId": "uuid-of-the-building-where-the-space-is",
+  "isOccupied": true if occupied, false if release
+}
+</code>

DokuWiki

Site Tools

Differences

Page Tools