# Senaste föreläsningar från Play

## Versionshantering
Alla API:er skall versioneras med hjälp av URI:n. Den första versionen skall vara `v1`.
Inga bakåtbrytande ändringar får göras i en version, istället skall en ny version skapas.

När en ny version skapas skall den gamla versionen finnas kvar i minst någon tid för att
tillåta migrering. Alla endpoints ska finnas i alla versioner även om dom inte har ändrats.

### Exempel på ändringar som tillåts inom en version
- Lägga till nya fält i ett svar
- Lägga till nya API:er
- Lägga till nya feltyper

## 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 senaste föreläsningar
```
> GET /v1/lectures/recent?course=INPRG&course=MDI2&course=DAI1
> Accept: application/json
> Accept-Language: sv
> Authorization: Bearer <oauth 2 token>
```

```< 200 OK
< Content-Type: application/json
< Content-Language: sv
```

```json
[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "title": "Introduktion till programmering",
    "description": "En grundläggande kurs i programmering med Python.",
    "duration": "PT2H04M",
    "created_at": "2024-06-01T10:00:00Z",
    "thumbnail_url": "https://example.com/thumbnails/intro-to-programming.png",
    "course": {
      "name": "Introduktion till programmering",
      "short_name": "INPRG",
      "semester": "VT2022"
    },
  },
  ...
]
```

## Hämta föreläsningar på en kurs
```
> GET /v1/lectures?course=INPRG&semester=HT2001
> Accept: application/json
> Accept-Language: en
> Authorization: Bearer <oauth 2 token>
```

```
< 200 OK
< Content-Type: application/json
< Content-Language: en
```

```json
[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "title": "Introduction to Programming",
    "description": "A basic course in programming with Python.",
    "duration": "PT2H04M",
    "created_at": "2024-06-01T10:00:00Z",
    "thumbnail_url": "https://example.com/thumbnails/intro-to-programming.png",
    "course": {
      "name": "Introduction to Programming",
      "short_name": "INPRG",
      "semester": "VT2022"
    },
  },
  ...
]
```