api-spec/play/api.md

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

< Content-Type: application/json
< Content-Language: sv

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

[
  {
    "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"
    },
  },
  ...
]