api-spec/daisy/grupprumsbokning.md

Specifikation för grupprumsbokning i Daisys nya API

Säkerhet/autentisering

API:t skall använda sig av OAuth 2.0 med JSON Web Tokens (JWT) i JSON Web Signature (JWS) 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 och språket ska anges i svaret med hjälp av 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 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

{
  "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

{
  "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 <oauth 2 token>
> 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

{
  "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 <oauth 2 token>
> 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

{
  "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 😃<script>alert('hej')</script>"
}

Svar

Allt gick bra

< 200 OK
< Content-Type: application/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

{
  "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

{
  "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 <oauth 2 token>
> Accept: application/json

Svar

< 200 OK
< Content-Type: application/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"
    ]
  }
]

Uppdatera en bokning

Förfrågan

> PUT /v1/bookings/group-rooms/{booking_id}
> Authorization: Bearer <oauth 2 token>
> Accept: application/json
> Content-Type: application/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 😃<script>alert('hej')</script>"
}

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 <oauth 2 token>

Svar

< 204 No Content