172 lines
4.4 KiB
Markdown
172 lines
4.4 KiB
Markdown
# 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"
|
|
},
|
|
},
|
|
...
|
|
]
|
|
```
|