# Specifikation för att hämta kurser och scheman i Daisys nya API

## Hämta lista på kurser

### Förfrågan

```
> GET /v1/me/courses?status=ongoing,unfinished,upcoming,finished,credited,aborted
> Authorization: Bearer <oauth 2 token>
> Accept: application/json
```

Ger mig (identifierad av oauth 2 token) alla mina kurser med delkurstillfällen jag är registrerad/deltagare på.

### Svar

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

```json
[
    {
        "code": "PROLED",
        "name": "Praktisk Projektledning",
        "ects": 7.5,
        "program": null,
        "status": "enum string", // ongoing, unfinished, upcoming, finished, credited, aborted
        "occasions": [
            {
                "id": "123456",
                "semester": "VT2025",
                "start": "2025-01-03",
                "end": "2025-06-03",
                "teachers": [{ "principal": "teacher1@su" }, { "principal": "teacher2@su" }]
            },
            {
                "id": "1234567",
                "semester": "HT2025",
                "start": "2025-09-03",
                "end": "2026-01-03",
                "teachers": [{ "principal": "teacher1@su" }, { "principal": "teacher2@su" }]
            }
        ]
    },
    {
        "code": "PROTO2",
        "name": "Prototyper inom interaktionsdesign II",
        "ects": 7.5,
        "program": { "code": "SIADK", "name": "Kandidatprogram i interaktionsdesign" },
        "status": "enum string", // ongoing, unfinished, upcoming
        "occasions": [
            {
                "id": "123456",
                "semester": "HT2025",
                "start": "2025-09-03",
                "end": "2026-01-03",
                "teachers": [{ "principal": "teacher3@su" }, { "principal": "teacher4@su" }]
            }
        ]
    }
]
```

## Hämta kursinformation
### Förfrågan

```> GET /v1/courses/:courseId
> Authorization: Bearer <oauth 2 token>
> Accept-Language: sv
> Accept: application/json
```

### Svar

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

```json
{
    "code": "PROLED",
    "name": "Praktisk Projektledning",
    "description": "En kurs i praktisk projektledning där du får lära dig att planera, genomföra och utvärdera projekt inom IT-området.",
    "ects": 7.5,
    "id": "1234567",
    "semester": "HT2025",
    "start": "2025-09-03",
    "end": "2026-01-03",
    "teachers": [{ "principal": "teacher1@su" }, { "principal": "teacher2@su" }],
    "examinations": [
        {
            "name": "Tentamen",
            "code": "PROLED-TENTA-HT25",
            "result": { // senaste resultatet för den här tentan
                "grade": "A",
                "date": "2025-12-15"
            }
        }
    ]
}
```




## Hämta kursschema

### Förfrågan

```
> GET /v1/courses/:courseId/schedule
> Authorization: Bearer <oauth 2 token>
> Accept: application/json
```

**`type` (string, enum):**

| Value    | Description  |
| -------- | ------------ |
| teaching | Undervisning |
| exam     | Tenta        |
| deadline | Deadline     |

```json
[
    {
        "type": "teaching",
        "name": "Föreläsning 1",
        "shortName": "F1",
        "startTime": "2025-01-03T10:00:00Z",
        "endTime": "2025-01-03T12:00:00Z",
        "location": [{ "name": "L30" }],
        "description": "Lecture on API Design",
        "participants": [
            { "principal": "teacher1@su", "role": "teacher" },
            { "principal": "teacher2@su", "role": "teacher" }
        ]
    },
    {
        "type": "teaching",
        "name": "Workshop 1",
        "shortName": "W1",
        "group": "1",
        "startTime": "2025-01-03T10:00:00Z",
        "endTime": "2025-01-03T12:00:00Z",
        "location": [{ "name": "L50" }],
        "description": "Workshop on Microservices",
        "participants": [
            { "principal": "teacher1@su", "role": "teacher" },
            { "principal": "teacher2@su", "role": "teacher" }
        ]
    }
]
```

## Hämta personligt schema

### Förfrågan

```
> GET /v1/users/me/schedule?&startTime=ISO-timestamp&endTime=ISO-timestamp
> Authorization: Bearer <oauth 2 token>
> Accept: application/json
```
Identifierare bör vara så stabil som möjligt och unik för varje system. Ska vara prefixad med systemets namn (ex. daisy-prog2-ht25-ordinarie-tenta).

### Stanardschema för event:

```json
{
    "title": "string",
    "description": "string", //optional
    "identifier": "string",
    "eventType": "enum string",
    "startTime": "ISO-timestamp",
    "endTime": "ISO-timestamp", // optional
    "details": {
        // beroende på eventType
        // courseEventType
        // bookingEventType
        // etc
    }
}
```

**`EventType` (string, enum):**

| Value        | Description      |
| ------------ | ---------------- |
| teaching     | Undervisning     |
| room booking | Bokningar av rum |
| deadline     | Deadline, sista datum för kursregistrering, tentaanmälan, kursutvärdering         |


Details-objekt beroende på eventType:

```json
{
    "courseEventType": {
        "locations": [{ "roomName": "string" }],
        "courseCode": "string",
        "occasionId": "string",
        "semester": "string",
        "type": "enum string", // teaching, exam, deadline etc
        "shortName": "string",
        "teachers": [{ "principal": "string" }]
    },
    "bookingEventType": {
        "locations": [{ "roomName": "string" }],
        "bookedBy": { "principal": "string" },
        "participants": [{ "principal": "string" }]
    },
    "deadlineEventType": {},
}
```

### Exempel

```json
[
    {
        "title": "Föreläsning 1",
        "description": "Lecture on API Design",
        "identifier": "daisy-proled-vt25-fl1",
        "eventType": "teaching",
        "startTime": "2025-01-03T10:00:00Z",
        "endTime": "2025-01-03T12:00:00Z",
        "details": {
            "locations": [{ "room": "L30" }],
            "courseCode": "PROLED",
            "occasionId": 123456,
            "semester": "VT2025",
            "type": "Undervisning",
            "shortname": "F1",
            "teachers": [{ "principal": "teacher1@su" }, { "principal": "teacher2@su" }]
        }
    },
    {
        "title": "Gruppmöte",
        "description": "Group Meeting",
        "identifier": "daisy-booking-12345",
        "eventType": "room booking",
        "startTime": "2025-01-03T09:00:00Z",
        "endTime": "2025-01-03T10:00:00Z",
        "details": {
            "locations": [{ "room": "G10:3" }],
            "bookedBy": { "principal": "student1@su" },
            "participants": [{ "principal": "student1@su" }, { "principal": "student2@su" }]
        }
    },
    {
        "description": "Tentaplugg - Don't forget the snacks",
        "title": "Tentaplugg",
        "identifier": "daisy-booking-123456",
        "eventType": "room booking",
        "startTime": "2025-01-03T09:00:00Z",
        "endTime": "2025-01-03T10:00:00Z",
        "details": {
            "participants": [{ "principal": "student1@su" }, { "principal": "student2@su" }]
        }
    }
]
```