normal
Zum Hauptinhalt springen

# Ankündigungen (News)

info

Ankündigungen informieren Stud.IP-Nutzer über neuste Ereignisse rund um die Lehre. In Stud.IP können Ankündigungen z.B. systemweit (global) oder für einen bestimmten Nutzerkreis erstellt werden.

## Schema "news"​

Ankündigungen bestehen aus ihrem Inhalt und einigen Meta-Daten. Die Dauer der Sichtbarkeit einer Anküdnigung wird durch ihre Attribute publication-start und end bestimmt (siehe Relationen).

### Attribute​

Attribut | Beschreibung
--- | ---
title | Name einer news
content | Inhalt einer News
mkdate | Erstellungs-Datum einer News
chdate | Datum der letzten Änderung
publication-start | Start der Sichtbarkeit für den Nutzerkreis einer News
publication-end | Ende der Sichtbarkeit für den Nutzerkreis einer News
comments-allowed | Bestimmung, ob Kommentare erlaubt sind (Boolean)

Ein Beispiel zum erstellen einer News anhand des Schemas folgt in News anlegen.

### Relationen​

Relation | Beschreibung
--- | ---
author | Ersteller einer News
ranges | global, institute, semester, course, users

Der Range einer News gibt an wo sie publiziert wird und somit auch für wen sie sichtbar ist.

## Schema "comments"​

Kommentare werden in Stud.IP an eine Ankündigung angehangen, wenn der Ersteller der News die Erlaubnis vergeben hat.

### Attribute​

Attribut | Beschreibung
--- | ---
content | Inhalt eines Kommentars
mkdate | Erstellungs-Datum
chdate | Datum der letzten Änderung

### Relationen​

Relation | Beschreibung
--- | ---
author | Der Ersteller des Kommentars
news | Die kommentierte News

## News anlegen​

Das Anlegen einer News ist in verschiedenen Kontexten möglich. Sie kann global als systemweite News, kursintern oder nutzerbezogen angelegt werden.

## Eine globale News anlegen​

### Route​

`POST /news`

### Autorisierung​

Die Erstellung einer globalen News erfordern zur Zeit noch Root-Rechte. Es wird diskutiert ob hier Adminrechte reichen.

    curl --request POST \
        --url https://example.com/news \
        --header "Content-Type: application/vnd.api+json" \
        --header "Authorization: Basic `echo -ne "root@studip:testing" | base64`" \
        --data
        '{"data": {"type": "news","attributes": {"title": "Neue News","comments-allowed": true,"publication-start": "2020-01-01T12:12:12+00:00","publication-end": "2021-01-01T12:12:12+00:00","content": "Eine neue News sieht das Tageslicht."}}}'

## Eine Kurs-News anlegen​

`POST /courses/{id}/news`

    curl --request POST \
        --url https://example.com/courses/<COURSE-ID>/news \
        --header "Content-Type: application/vnd.api+json" \
        --header "Authorization: Basic `echo -ne "test_dozent:testing" | base64`" \
        --data
        '{"data": {"type": "news","attributes": {"title": "Neue News","comments-allowed": true,"publication-start": "2020-01-01T12:12:12+00:00","publication-end": "2021-01-01T12:12:12+00:00","content": "Eine neue News sieht das Tageslicht."}}}'

Parameter | Beschreibung
--- | ---
id | Die ID des Kurses

### Autorisierung​

Der Nutzer muss mindestens Dozenten- oder Adminrechte innerhalb des Kurses haben.

## Eine Nutzer-News anlegen​

`POST /users/{id}/news`

    curl --request POST \
        --url https://example.com/users/<USER-ID>/news \
        --header "Content-Type: application/vnd.api+json" \
        --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \
        --data
        '{"data": {"type": "news","attributes": {"title": "Neue News","comments-allowed": true,"publication-start": "2020-01-01T12:12:12+00:00","publication-end": "2021-01-01T12:12:12+00:00","content": "Eine neue News sieht das Tageslicht."}}}'

Parameter | Beschreibung
--- | ---
id | Die ID des Users

### Autorisierung​

Der Nutzer muss mindestens User-Rechte haben.

## Einen Kommentar anlegen​

`POST /news/{id}/comments`

    curl --request POST \
        --url https://example.com/news/<NEWS-ID>/comments \
        --header "Content-Type: application/vnd.api+json" \
        --header "Authorization: Basic `echo -ne "test_dozent:testing" | base64`" \
        --data
        '{"data": {"type": "comments","attributes": {"content": "Ein Kommentar wurde geupdatet"}}}'

### Autorisierung​

Der Nutzer muss mindestens User-Rechte haben.

Parameter | Beschreibung
--- | ---
id | Die ID der News

## Eine News ändern​

`PATCH /news/{id}`

Parameter | Beschreibung
--- | ---
id | Die ID der News

Die Data-Felder beim Update einer News sind optional.

    curl --request PATCH \
        --url https://example.com/news/<NEWS-ID> \
        --header "Content-Type: application/vnd.api+json" \
        --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \
        --data
        '{"data": {"type": "news","attributes": {"title": "Aenderungen","comments-allowed": true,"publication-start": "2020-01-01T12:12:12+00:00","publication-end": "2021-01-01T12:12:12+00:00","content": "Eine News wurde geaendert."}}}'

### Autorisierung​

Der Nutzer muss Inhaber der News sein oder die entsprechenden Root-Rechte besitzen.

## Eine News ansehen​

`GET /news/{id}`

Parameter | Beschreibung
--- | ---
id | Die ID der News

    curl --request GET \
        --url https://example.com/news/<NEWS-ID> \
        --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \

### Autorisierung​

Der Nutzer muss Inhaber der News sein oder die entsprechenden Range-Rechte besitzen.

> Der Request liefert JSON ähnlich wie dieses:

    {
      "data": {
        "type": "news",
        "id": "6a8be7e4859e9c781ecc47a2c3498435",
        "attributes": {
          "title": "A testing title",
          "content": "Lorem ipsum dolor sit amet, consectetur adipisicing elit",
          "mkdate": "2019-04-23T12:10:26+02:00",
          "chdate": "2019-04-23T12:10:26+02:00",
          "publication-start": "2019-04-23T12:10:26+02:00",
          "publication-end": "2019-05-07T12:10:26+02:00",
          "comments-allowed": true
        },
        "relationships": {
          "author": {
            "data": {
              "type": "users",
              "id": "e7a0a84b161f3e8c09b4a0a2e8a58147"
            },
            "links": {
              "related": "jsonapi.php/v1/users/e7a0a84b161f3e8c09b4a0a2e8a58147"
            }
          },
          "ranges": {
            "data": [

            ],
            "links": {
              "self": "jsonapi.php/v1/news/6a8be7e4859e9c781ecc47a2c3498435/relationships/ranges"
            }
          }
        },
        "links": {
          "self": "jsonapi.php/v1/news/6a8be7e4859e9c781ecc47a2c3498435"
        }
      }
    }

## Alle Kurs-News​

`GET /courses/{id}/news`

Parameter | Beschreibung
--- | ---
id | Die ID des Kurses

    curl --request GET \
        --url https://example.com/course/<COURSE-ID>/news \
        --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \

### Autorisierung​

Der Nutzer muss mindestens Teilnehmer des Kurses sein.

> Der Request liefert JSON ähnlich wie dieses:

    {
      "meta": {
        "page": {
          "offset": 0,
          "limit": 30,
          "total": 4
        }
      },
      "links": {
        "first": "/stud35/plugins.php/argonautsplugin/courses/1b7d3834e42c1569947e0eab7b63ed19/news?page%5Boffset%5D=0&page%5Blimit%5D=30",
        "last": "/stud35/plugins.php/argonautsplugin/courses/1b7d3834e42c1569947e0eab7b63ed19/news?page%5Boffset%5D=0&page%5Blimit%5D=30"
      },
      "data": [
        {
          "type": "news",
          "id": "9dc34d7414e9d6c2789923649a64673e",
          "attributes": {
            "title": "Fakenews",
            "content": "This is fakenews232",
            "mkdate": "2018-06-20T10:40:43+02:00",
            "chdate": "2018-06-20T10:57:37+02:00",
            "publication-start": "2018-06-21T12:00:00+02:00",
            "publication-end": "2066-12-09T22:00:00+01:00",
            "comments-allowed": true
          },
          "relationships": {
            "author": {
              "data": {
                "type": "users",
                "id": "76ed43ef286fb55cf9e41beadb484a9f"
              },
              "links": {
                "related": "/stud35/plugins.php/argonautsplugin/users/76ed43ef286fb55cf9e41beadb484a9f"
              }
            },
            "ranges": {
              "data": [
                {
                  "type": "courses",
                  "id": "1b7d3834e42c1569947e0eab7b63ed19"
                }
              ],
              "links": {
                "self": "/stud35/plugins.php/argonautsplugin/news/9dc34d7414e9d6c2789923649a64673e/relationships/ranges"
              }
            }
          },
          "links": {
            "self": "/stud35/plugins.php/argonautsplugin/news/9dc34d7414e9d6c2789923649a64673e"
          }
        },
        {
          "type": "news",
          "id": "0e8df7da383d7515c4dc081bfe889897",
          "attributes": {
            "title": "Fakenews",
            "content": "This is fakenews232",
            "mkdate": "2018-06-19T16:08:51+02:00",
            "chdate": "2018-06-20T09:50:02+02:00",
            "publication-start": "2018-06-19T16:08:51+02:00",
            "publication-end": "2066-12-05T15:08:51+01:00",
            "comments-allowed": true
          },
          "relationships": {
            "author": {
              "data": {
                "type": "users",
                "id": "76ed43ef286fb55cf9e41beadb484a9f"
              },
              "links": {
                "related": "/stud35/plugins.php/argonautsplugin/users/76ed43ef286fb55cf9e41beadb484a9f"
              }
            },
            "ranges": {
              "data": [
                {
                  "type": "courses",
                  "id": "1b7d3834e42c1569947e0eab7b63ed19"
                }
              ],
              "links": {
                "self": "/stud35/plugins.php/argonautsplugin/news/0e8df7da383d7515c4dc081bfe889897/relationships/ranges"
              }
            }
          },
          "links": {
            "self": "/stud35/plugins.php/argonautsplugin/news/0e8df7da383d7515c4dc081bfe889897"
          }
        },
        {
          "type": "news",
          "id": "191ce64590a28b3e038b09e85ea53178",
          "attributes": {
            "title": "Fakenews",
            "content": "This is fakenews",
            "mkdate": "2018-05-08T11:42:11+02:00",
            "chdate": "2018-05-08T11:42:11+02:00",
            "publication-start": "2018-05-08T11:42:11+02:00",
            "publication-end": "2066-09-19T20:24:22+01:00",
            "comments-allowed": true
          },
          "relationships": {
            "author": {
              "data": {
                "type": "users",
                "id": "76ed43ef286fb55cf9e41beadb484a9f"
              },
              "links": {
                "related": "/stud35/plugins.php/argonautsplugin/users/76ed43ef286fb55cf9e41beadb484a9f"
              }
            },
            "ranges": {
              "data": [
                {
                  "type": "courses",
                  "id": "1b7d3834e42c1569947e0eab7b63ed19"
                }
              ],
              "links": {
                "self": "/stud35/plugins.php/argonautsplugin/news/191ce64590a28b3e038b09e85ea53178/relationships/ranges"
              }
            }
          },
          "links": {
            "self": "/stud35/plugins.php/argonautsplugin/news/191ce64590a28b3e038b09e85ea53178"
          }
        },
        {
          "type": "news",
          "id": "a355b8d628d8656eb93dc527fe1209f3",
          "attributes": {
            "title": "Fakenews",
            "content": "This is fakenews",
            "mkdate": "2018-05-08T11:35:56+02:00",
            "chdate": "2018-05-08T11:35:56+02:00",
            "publication-start": "2018-05-08T11:35:55+02:00",
            "publication-end": "2066-09-19T20:11:50+01:00",
            "comments-allowed": true
          },
          "relationships": {
            "author": {
              "data": {
                "type": "users",
                "id": "76ed43ef286fb55cf9e41beadb484a9f"
              },
              "links": {
                "related": "/stud35/plugins.php/argonautsplugin/users/76ed43ef286fb55cf9e41beadb484a9f"
              }
            },
            "ranges": {
              "data": [
                {
                  "type": "courses",
                  "id": "1b7d3834e42c1569947e0eab7b63ed19"
                }
              ],
              "links": {
                "self": "/stud35/plugins.php/argonautsplugin/news/a355b8d628d8656eb93dc527fe1209f3/relationships/ranges"
              }
            }
          },
          "links": {
            "self": "/stud35/plugins.php/argonautsplugin/news/a355b8d628d8656eb93dc527fe1209f3"
          }
        }
      ]
    }

## Alle Nutzer-News​

`GET /users/{id}/news`

Parameter | Beschreibung
--- | ---
id | Die ID des Nutzers

    curl --request GET \
        --url https://example.com/user/<USER-ID>/news \
        --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \

### Autorisierung​

Der Nutzer muss mindestens eingeloggt sein oder über Root-Rechte verfügen.

> Der Request liefert JSON ähnlich wie dieses:

    {
      "data": {
        "type": "news",
        "id": "0e8df7da383d7515c4dc081bfe889897",
        "attributes": {
        "title": "Neue News",
        "content": "Eine neue News sieht das Tageslicht.",
        "mkdate": "2018-06-19T16:08:51+02:00",
        "chdate": "2018-08-15T14:22:38+02:00",
        "publication-start": "2018-06-19T16:08:51+02:00",
        "publication-end": "2066-12-05T15:08:51+01:00",
        "comments-allowed": true
        },
        "relationships": {
          "author": {
            "data": {
              "type": "users",
              "id": "76ed43ef286fb55cf9e41beadb484a9f"
            },
            "links": {
              "related": "/stud35/plugins.php/argonautsplugin/users/76ed43ef286fb55cf9e41beadb484a9f"
            }
          },
          "ranges": {
            "data": [
            {
              "type": "users",
              "id": "1b7d3834e42c1569947e0eab7b63ed19"
            }
            ],
              "links": {
              "self": "/stud35/plugins.php/argonautsplugin/news/0e8df7da383d7515c4dc081bfe889897/relationships/ranges"
              }
          }
        },
        "links": {
          "self": "/stud35/plugins.php/argonautsplugin/news/0e8df7da383d7515c4dc081bfe889897"
        }
      }
    }

## Alle News-Kommentare​

`GET /news/{id}/comments`

Parameter | Beschreibung
--- | ---
id | Die ID einer News

## Alle globalen News​

`GET /studip/news`

    curl --request GET \
        --url https://example.com/user/studip/news \
        --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \

### Autorisierung​

Der Nutzer muss mindestens eingeloggt sein oder über Root-Rechte verfügen.

> Der Request liefert JSON ähnlich wie dieses:

    {
      "data": {
        "type": "news",
        "id": "0e8df7da383d7515c4dc081bfe889897",
        "attributes": {
        "title": "Globale News",
        "content": "Eine neue News sieht das Tageslicht.",
        "mkdate": "2018-06-19T16:08:51+02:00",
        "chdate": "2018-08-15T14:22:38+02:00",
        "publication-start": "2018-06-19T16:08:51+02:00",
        "publication-end": "2066-12-05T15:08:51+01:00",
        "comments-allowed": true
        },
        "relationships": {
          "author": {
            "data": {
              "type": "users",
              "id": "76ed43ef286fb55cf9e41beadb484a9f"
            },
            "links": {
              "related": "/stud35/plugins.php/argonautsplugin/users/76ed43ef286fb55cf9e41beadb484a9f"
            }
          },
          "ranges": {
            "data": [
            {
              "type": "global",
              "id": "studip"
            }
            ],
              "links": {
              "self": "/stud35/plugins.php/argonautsplugin/news/0e8df7da383d7515c4dc081bfe889897/relationships/ranges"
              }
          }
        },
        "links": {
          "self": "/stud35/plugins.php/argonautsplugin/news/0e8df7da383d7515c4dc081bfe889897"
        }
      }
    }

## Alle News des aktuell eingeloggten Nutzers abrufen​

`GET /news`

    curl --request GET \
        --url https://example.com/news \
        --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \

### Autorisierung​

Der Nutzer muss mindestens eingeloggt sein oder über Root-Rechte verfügen.

> Der Request liefert JSON ähnlich wie dieses:

    {
      "data": {
        "type": "news",
        "id": "0e8df7da383d7515c4dc081bfe889897",
        "attributes": {
        "title": "Neue News",
        "content": "Eine neue News sieht das Tageslicht.",
        "mkdate": "2018-06-19T16:08:51+02:00",
        "chdate": "2018-08-15T14:22:38+02:00",
        "publication-start": "2018-06-19T16:08:51+02:00",
        "publication-end": "2066-12-05T15:08:51+01:00",
        "comments-allowed": true
        },
        "relationships": {
          "author": {
            "data": {
              "type": "users",
              "id": "76ed43ef286fb55cf9e41beadb484a9f"
            },
            "links": {
              "related": "/stud35/plugins.php/argonautsplugin/users/76ed43ef286fb55cf9e41beadb484a9f"
            }
          },
          "ranges": {
            "data": [
            {
              "type": "users",
              "id": "1b7d3834e42c1569947e0eab7b63ed19"
            }
            ],
              "links": {
              "self": "/stud35/plugins.php/argonautsplugin/news/0e8df7da383d7515c4dc081bfe889897/relationships/ranges"
              }
          }
        },
        "links": {
          "self": "/stud35/plugins.php/argonautsplugin/news/0e8df7da383d7515c4dc081bfe889897"
        }
      }
    }

## Eine News löschen​

`DELETE /news/{id}`

Parameter | Beschreibung
--- | ---
id | Die ID der News

### Authorisierung​

Diese Route kann nur vom Nutzer der betreffenden Nachrichten genutzt werden.

    curl --request DELETE \
        --url https://example.com/news/<NEWS-ID> \
        --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \

### Autorisierung​

Der Nutzer muss mindestens eingeloggt sein oder über Root-Rechte verfügen.

## Einen Kommentar löschen​

`DELETE /comments/{id}`

Parameter | Beschreibung
--- | ---
id | Die ID eines Kommentars

    curl --request DELETE \
        --url https://example.com/comments/studip/news \
        --header "Authorization: Basic `echo -ne "test_autor:testing" | base64`" \

## Alle News-Ranges​

`GET /news/{id}/relationships/ranges`

see http://jsonapi.org/format/#fetching-relationships

## News-Ranges setzen​

`PATCH /news/{id}/relationships/ranges`

see http://jsonapi.org/format/#crud-updating-to-many-relationships

## News-Ranges hinzufügen​

`POST /news/{id}/relationships/ranges`

see http://jsonapi.org/format/#crud-updating-to-many-relationships

## News-Ranges löschen​

`DELETE /news/{id}/relationships/ranges`

see http://jsonapi.org/format/#crud-updating-to-many-relationships