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](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 <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
```

```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
```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
#### 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 <oauth 2 token>
> Accept: application/json
```
### Svar
```
< 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"
    ]
  }
]
```

## 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
```

```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
```