# Specifikation för grupprumsbokning i Daisys nya API ## Säkerhet/autentisering API:t skall använda sig av [OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc6749) med [JSON Web Tokens (JWT)](https://datatracker.ietf.org/doc/html/rfc7519) i [JSON Web Signature (JWS)](https://datatracker.ietf.org/doc/html/rfc7515) format för autentisering och avgöra behörigheter på principalen (`sub`) som identifieras av token och eventuella `entitlements`. För mer information se https://oauth2.dsv.su.se/ ## Prestandakrav 99% av alla giltiga förfrågningar måste svaras på inom 100ms. Detta måste gälla hela tiden genom att mäta i ett kort rullande fönster, inte bara genomsnittligt över en längre period. ## Internationalisering Om en lokal eller annan data har namn (eller annat attribut) på flera språk skall värdet baseras på HTTP headern [`Accept-Language`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Accept-Language) och språket ska anges i svaret med hjälp av [`Content-Language`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Language) om inget av språken i `Accept-Language` finns skall det falla tillbaka på engelska. Denna internationalisering måste även appliceras på felmeddelanden; `title`, `detail`, och eventuella extra attribut. ### Exempel med språk som inte stöds ``` > GET /lokal > Accept-Language: de ``` ``` < 200 OK < Content-Language: en ``` ``` { "name": "Meeting room" } ``` ### Exempel med språk som stöds ``` > GET /lokal > Accept-Language: sv ``` ``` < 200 OK < Content-Language: sv ``` ``` { "name": "Mötesrum" } ``` ## Felhantering Fel anges i [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) format (Problem details) Alla olika feltyper (`type` attribut) skall dokumenteras ### Exempel på generella fel som kan förekomma i alla anrop #### Ej behörig ``` < 403 Forbidden < Content-Type: application/problem+json ``` ```json { "type": "daisy:forbidden", "title": "You can not perform this action", "detail": "You may not book a group room because you are not a student at SU", "instance": "/v1/bookings/group-rooms" } ``` #### Felaktigt format på datum/tid ``` < 400 Bad request < Content-Type: application/problem+json ``` ```json { "type": "daisy:bad-request", "title": "Bad request", "detail": "Badly formatted request", "instance": "/v1/bookings/group-rooms", "violations": { "start_time": "Must be in format YYYY-MM-DDTHH:MM", "name": "Too long, max 100 characters" } } ``` ## Hämta komplett kontext för att genomföra en bokning ### Förfrågan ``` > GET /v1/bookings/group-rooms?size={small,large} > Authorization: Bearer > Accept: application/json ``` Ger mig (identifierad av oauth 2 token) all information om dom små/stora grupprum jag kan boka inklusive alla bokningar inom det bokningsbara intervallet. Givet att datum är 2024-11-01 och bokningsbara intervallet är 14 dagar är nedan ett exempel på svar ### Svar ``` < 200 OK < Content-Type: application/json ``` ```json { "rooms": [ { "id": "1", "name": "Small Room 1", "capacity": 5, "bookings": [ { "start": "2024-11-03T10:00:00", "end": "2024-11-03T12:00:00" } ] }, { "id": "abcd-uuid8v3-blaj-blaj", "name": "Small Room 2", "capacity": 5, "bookings": [ { "start": "2024-11-10T14:00:00", "end": "2024-11-10T18:00:00" } ] } ], "maxBookableLength": "PT4H", "earliestBookingTime": "08:00:00", "latestBookingTime": "20:00:00", "minimumParticipants": 2, "maxDaysInFuture": 14 } ``` ## Göra en bokning ### Förfrågan ``` > POST /v1/bookings/group-rooms > Authorization: Bearer > Accept: application/json > Content-Type: application/json ``` `additional_participants` inkluderar inte mig själv (som står i oauth 2 token) `name` skall kunna inkludera full utf-8 ```json { "room_id": "123462abc", "start_time": "2024-11-08T12:00", "end_time": "2024-11-08T13:00", "additional_participants": [ "stud1234@su.se", "komp153n@su.se" ], "name": "Min bokning för tentaplugg 😃" } ``` ### Svar #### Allt gick bra ``` < 200 OK < Content-Type: application/json ``` ```json { "booking_id": "leif43253240", "name": "Team standup", "room_name": "G5:7", "start_time": "2024-11-20T08:00", "end_time": "2024-11-20T10:00", "additional_participants": [ "kaan8888@su.se", "joan7777@su.se" ] } ``` #### För lång bokning ``` < 400 Bad request < Content-Type: application/problem+json ``` ```json { "type": "daisy:duration-too-long", "title": "Booking exceeds max length", "detail": "You may only book max four hours and you tried to book 5", "instance": "/v1/bookings/group-rooms" } ``` #### För få deltagare ``` < 400 Bad request < Content-Type: application/problem+json ``` ```json { "type": "daisy:too-few-participants", "title": "Booking needs more participants", "detail": "You may only book with at least two participants, not by yourself", "instance": "/v1/bookings/group-rooms" } ``` ## Hämta mina bokningar ### Förfrågan ``` > GET /v1/bookings/group-rooms/mine > Authorization: Bearer > Accept: application/json ``` ### Svar ``` < 200 OK < Content-Type: application/json ``` ```json [ { "booking_id": "leif43253240", "name": "Team standup", "room_name": "G5:7", "booked_by": "stud1111@su.se", "start_time": "2024-11-20T08:00", "end_time": "2024-11-20T10:00", "additional_participants": [ "kaan8888@su.se", "joan7777@su.se" ] } ] ``` ## Uppdatera en bokning ### Förfrågan ``` > PUT /v1/bookings/group-rooms/{booking_id} > Authorization: Bearer > Accept: application/json > Content-Type: application/json ``` ```json { "room_id": "123462abc", "start_time": "2024-11-08T12:00", "end_time": "2024-11-08T13:00", "additional_participants": [ "stud1234@su.se", "komp153n@su.se" ], "name": "Min bokning för tentaplugg 😃" } ``` ### Svar Se samma svar som för att skapa bokning ## Ta bort en bokning ### Förfrågan ``` > DELETE /v1/bookings/group-rooms/{booking_id} > Authorization: Bearer ``` ### Svar ``` < 204 No Content ```