Commit 33350032 authored by Art4's avatar Art4

Merge branch 'master' into develop

parents ff0a17a5 439ffce9
Pipeline #175183078 passed with stages
in 6 minutes and 26 seconds
......@@ -52,6 +52,12 @@ build-docs:
when: never
- when: on_success
before_script:
- apt-get update
- curl -sL https://deb.nodesource.com/setup_10.x | bash -
- apt-get --yes install git zip unzip nodejs
- nodejs --version
- npm --version
- npm install
- cd docs
- gem install bundler
- bundle -v
......@@ -61,6 +67,33 @@ build-docs:
script:
- bundle exec jekyll build --destination ../public/
- cd ..
- mkdir -p ./public/spec/core
- echo "Render HTML for 0.16"
- cp -r ./spec ./public/spec/core/0.16
- node_modules/.bin/aglio -i ./public/spec/core/0.16/apiary.apib --no-theme-condense --theme-full-width -o ./public/spec/core/0.16/index.html
- echo "Render HTML for next version"
- git fetch origin develop:develop
- git checkout develop -- ./spec
- cp -r ./spec ./public/spec/core/next
- git reset HEAD ./spec
- git checkout -- ./spec
- node_modules/.bin/aglio -i ./public/spec/core/next/apiary.apib --no-theme-condense --theme-full-width -o ./public/spec/core/next/index.html
- echo "Render HTML for 0.15"
- git checkout 0.15.2 -- apiary.apib
- mkdir -p ./public/spec/core/0.15
- mv ./apiary.apib ./public/spec/core/0.15/apiary.apib
- node_modules/.bin/aglio -i ./public/spec/core/0.15/apiary.apib --no-theme-condense --theme-full-width -o ./public/spec/core/0.15/index.html
- echo "Render HTML for 0.14"
- git checkout 0.14 -- apiary.apib
- mkdir -p ./public/spec/core/0.14
- mv ./apiary.apib ./public/spec/core/0.14/apiary.apib
- node_modules/.bin/aglio -i ./public/spec/core/0.14/apiary.apib --no-theme-condense --theme-full-width -o ./public/spec/core/0.14/index.html
- echo "Render HTML for 0.13"
- git checkout 0.13 -- apiary.apib
- mkdir -p ./public/spec/core/0.13
- mv ./apiary.apib ./public/spec/core/0.13/apiary.apib
- node_modules/.bin/aglio -i ./public/spec/core/0.13/apiary.apib --no-theme-condense --theme-full-width -o ./public/spec/core/0.13/index.html
cache:
key: build
paths:
......
......@@ -14,6 +14,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
- new attribute `content_html` in `Post` resources with the parsed HTML content
- new attribute `reactions_given` in `Post` resources with an array of reactions given by the authorized user
- new attribute `reactions_count` in `Post` resources with an object of reactions and counts given by all users
- new docs generated from API Blueprint files
### Changed
......
---
title: "Youthweb-API 0.16 liefert mehr Daten zu Posts und erlaubt das Bearbeiten"
categories: API
tags: [api, release]
summary: "Youthweb-API 0.16 liefert den geparsten Content zu Posts und erlaubt das Vergeben von Reactions. Außerdem wird die API-Dokumentation verändert und in Zukunft aus API Blueprint generiert."
---
## Neues zu den Posts
Bei den Posts gibt es jetzt [drei neue Attribute](spec/core/0.16/index.html#posts-post-get):
- `content_html` gibt den Content als fertig geparstes HTML zurück
- `reactions_given` ist ein Array, dass die Reactions enthält, die der angemeldete User einem Post gegeben hat und
- `reactions_count` enthält Informationen, welche Reactions wie oft ein Post bekommen hat.
Neu ist auch, dass Posts jetzt bearbeitet werden können. Der Endpoint dazu lautet `PATCH /posts/<uuid>`.
Vorausgesetzt ein User darf einen Post bearbeiten, können die Attribute `title`, `content`, `view_allowed_for`, `comments_allowed` und `reactions_given` verändert werden. Das Verändern der ersten beiden Attribute sorgt dafür, dass sich das Attribute `update_at` aktualisiert.
Wenn nur Lesezugriff auf einen Post besteht, kann nur das Attribute `reactions_given` verändert werden. Und wenn kein Lesezugriff besteht, dann wird wie bisher ein `401` bzw `403` Error zurückgegeben.
## Neue Dokumentation
Das separate Pflegen der API Dokumentation ist teilweise sehr aufwendig. Durch das doppelte Schreiben der API Blueprints, Behat-Features und der Dokumentation schleichen sich gerne Fehler ein führen zu einer unvollständigen Dokumentation.
Daher bieten wir jetzt neu [eine automatisch generierte Dokumentation][api_endpoint_index] an, die mithilfe von [Aglio](https://github.com/danielgtaylor/aglio) aus den API Blueprint Dateien zu HTML gerendert wird.
Die alte Dokumentation wird noch bestehen bleiben, aber nicht mehr aktualisiert und wird in Zukunft entfernt werden.
## Veraltet
Bei der Post Resource werden automatisch die Relationships `author` und `parent` geladen. Dieses Verhalten wird sich in Zukunft ändern und es werden keine Relationships mehr automatisch geladen. Dadurch möchten wir die Responses in Zukunft kleiner halten.
Wenn deine App diese Relationships benötigt, dann solltest du sie ab sofort über den `include` Parameter im Querystring anfordern. Beispiel:
```
GET /posts/7b4d2748-4996-4fdd-912a-e966cb96715a?include=author,parent
```
Die Version 0.15 ist jetzt veraltet und zeigt eine Warnung im `meta`-Bereich an. In frühstens 6 Monaten wird die Unterstützung für diese Version entfernt. Verwende in deinen Apps jetzt die Version 0.16.
## Entfernt
**Breaking:** Der Support für die Versionen 0.13 and 0.14 wurde eingestellt. Sie waren seit Version 0.15 (08.09.2019) als deprecated markiert. Requests mit diesen Versionen erhalten jetzt einen 406 Error zurück.
{% include links.html %}
......@@ -8,6 +8,8 @@ permalink: api_endpoint_comments.html
folder: api
---
{% include important.html content="Diese Dokumentation wird nicht mehr gepflegt und wird in Zukunft entfernt. [Sieh dir stattdessen die neue Dokumentation an][api_endpoint_index]." %}
Dieser Endpoint kann zum Lesen eines Comments verwendet werden.
## Read
......
......@@ -8,6 +8,8 @@ permalink: api_endpoint_events.html
folder: api
---
{% include important.html content="Diese Dokumentation wird nicht mehr gepflegt und wird in Zukunft entfernt. [Sieh dir stattdessen die neue Dokumentation an][api_endpoint_index]." %}
Dieser Endpoint liefert die Events, die in einem bestimmten Zeitraum stattfinden oder ein bestimmtes Event.
## List
......
......@@ -8,6 +8,8 @@ permalink: api_endpoint_friends.html
folder: api
---
{% include important.html content="Diese Dokumentation wird nicht mehr gepflegt und wird in Zukunft entfernt. [Sieh dir stattdessen die neue Dokumentation an][api_endpoint_index]." %}
Dieser Endpoint kann zum Lesen eines `Friends` verwendet werden.
`Friends` sind die Verbindungspunkte zwischen zwei User. User lassen sich mithilfe der `Friends` als [gerichteter Graph](https://de.wikipedia.org/wiki/Graph_(Graphentheorie)) abbilden, wobei jeder User einen Knoten und jeder `Friend` eine Kante darstellt.
......
......@@ -11,10 +11,22 @@ folder: api
## Begriffe
- **Resource**: Eine Resource ist die Representation eines Objekts, zum Beispiel eines Users. Eine Resource, die vom Youthweb-Server geliefert wird, hat immer mindestens die Attribute `type` und `id`. Der Aufbau einer Resource ist [in JSON API spezifiziert](http://jsonapi.org/format/#document-resource-objects).
- **Endpoint**: Ein Endpoint ist eine Stelle in der Youthweb-API, mit der Daten ausgetauscht werden. Zum Beispiel liefert der Endpoint `/users/123` eine Resource, die den User mit der ID 123 representiert. Die übertragenen Daten an einem Entpoint enthalten also in fast allen Fällen eine oder mehrere Resourcen.
- **Endpoint**: Ein Endpoint ist eine Stelle in der Youthweb-API, mit der Daten ausgetauscht werden. Zum Beispiel liefert der Endpoint `/users/123` eine Resource, die den User mit der ID 123 representiert. Die übertragenen Daten an einem Endpoint enthalten also in fast allen Fällen eine oder mehrere Resourcen.
## API Blueprint
Die API ist in API Blueprint definiert und wird mit Aglio zu HTML gerendert. Aktuelle und ältere Versionen können hier angesehen werden:
| API | Version |
|--------------|-------------------------------------------|
| **current** | **[0.16](./spec/core/0.16/index.html)** |
| next | [develop](./spec/core/next/index.html) |
| deprecated | [0.15](./spec/core/0.15/index.html) |
## Übersicht
{% include important.html content="Diese folgende Dokumentation der Endpoints wird nicht mehr gepflegt und wird in Zukunft entfernt. [Sieh dir stattdessen die neue Dokumentation an][api_endpoint_index]." %}
| Endpoint | Beschreibung |
|---------------------------------------------------------|------------------------------------------------------------------|
| [/comments][api_endpoint_comments] | Liefert Comments-Resourcen |
......
......@@ -8,6 +8,8 @@ permalink: api_endpoint_me.html
folder: api
---
{% include important.html content="Diese Dokumentation wird nicht mehr gepflegt und wird in Zukunft entfernt. [Sieh dir stattdessen die neue Dokumentation an][api_endpoint_index]." %}
Dieser Endpoint ist ein Shortcut für `/users/{user_id}` und liefert eine [User-Resource][api_endpoint_users]. Er kann zum Beispiel verwendet werden, wenn die User-ID des autorisierten Users nicht bekannt ist, wodurch der `/users`-Endpoint noch nicht verwendet werden kann.
Siehe den [Endpoint `/users`][api_endpoint_users] für Informationen zur User-Resource.
......
......@@ -8,6 +8,8 @@ permalink: api_endpoint_object_comments.html
folder: api
---
{% include important.html content="Diese Dokumentation wird nicht mehr gepflegt und wird in Zukunft entfernt. [Sieh dir stattdessen die neue Dokumentation an][api_endpoint_index]." %}
Dieser Endpoint bietet die `/comments` Beziehungen zu einer Resource an. Die folgenden Resourcen haben eine `/comments` Beziehung:
- [Posts][api_endpoint_posts]
......
......@@ -8,6 +8,8 @@ permalink: api_endpoint_object_friends.html
folder: api
---
{% include important.html content="Diese Dokumentation wird nicht mehr gepflegt und wird in Zukunft entfernt. [Sieh dir stattdessen die neue Dokumentation an][api_endpoint_index]." %}
Dieser Endpoint bietet die `/friends` Beziehungen zu einer Resource an. Die folgenden Resourcen haben eine `/friends` Beziehung:
- [Users][api_endpoint_users]
......
......@@ -8,6 +8,8 @@ permalink: api_endpoint_object_posts.html
folder: api
---
{% include important.html content="Diese Dokumentation wird nicht mehr gepflegt und wird in Zukunft entfernt. [Sieh dir stattdessen die neue Dokumentation an][api_endpoint_index]." %}
Dieser Endpoint bietet die `/posts` Beziehungen zu einer Resource an. Die folgenden Resourcen haben eine `/posts` Beziehung:
- [Users][api_endpoint_users]
......
......@@ -8,6 +8,8 @@ permalink: api_endpoint_posts.html
folder: api
---
{% include important.html content="Diese Dokumentation wird nicht mehr gepflegt und wird in Zukunft entfernt. [Sieh dir stattdessen die neue Dokumentation an][api_endpoint_index]." %}
Dieser Endpoint kann zum Lesen oder Erstellen eines Posts verwendet werden.
## Read
......
......@@ -8,6 +8,8 @@ permalink: api_endpoint_stats.html
folder: api
---
{% include important.html content="Diese Dokumentation wird nicht mehr gepflegt und wird in Zukunft entfernt. [Sieh dir stattdessen die neue Dokumentation an][api_endpoint_index]." %}
Dieser Endpoint liefert Statistiken zu Usern, Gruppen und Forum.
## Read
......
......@@ -8,6 +8,8 @@ permalink: api_endpoint_users.html
folder: api
---
{% include important.html content="Diese Dokumentation wird nicht mehr gepflegt und wird in Zukunft entfernt. [Sieh dir stattdessen die neue Dokumentation an][api_endpoint_index]." %}
Dieser Endpoint liefert Daten zu einem User.
## Read
......
......@@ -22,19 +22,26 @@ Nach dem Release einer neuen Version garantieren wir den Support der Version ohn
| Version | Status | Veröffentlicht | Unterstützt bis |
|--------------|--------------------|----------------|---------------------------|
| [next] | :construction: | - | - |
| **0.17** | :heavy_check_mark: | 2020-??-?? | mindestens 2021-??-?? |
| **0.16** | :heavy_check_mark: | 2020-07-26 | mindestens 2021-07-26 |
| **0.15** | :warning: | 2019-09-08 | mindestens 2021-01-26 |
| 0.14 | :x: | 2019-01-13 | Version 0.16 - 2020-07-26 |
| 0.13 | :x: | 2018-12-16 | Version 0.16 - 2020-07-26 |
| **[0.16]** | :heavy_check_mark: | 2020-07-26 | mindestens 2021-07-26 |
| **[0.15]** | :warning: | 2019-09-08 | mindestens 2021-01-26 |
| [0.14] | :x: | 2019-01-13 | Version 0.16 - 2020-07-26 |
| [0.13] | :x: | 2018-12-16 | Version 0.16 - 2020-07-26 |
| 0.12 | :x: | 2017-07-16 | Version 0.15 - 2019-09-08 |
| 0.11 | :x: | 2017-07-02 | Version 0.15 - 2019-09-08 |
| 0.10 | :x: | 2017-06-18 | Version 0.15 - 2019-09-08 |
| 0.9 | :x: | 2017-06-04 | Version 0.15 - 2019-09-08 |
| 0.8 | :x: | 2017-05-21 | Version 0.15 - 2019-09-08 |
[next]: ./spec/core/next/index.html
[0.16]: ./spec/core/0.16/index.html
[0.15]: ./spec/core/0.15/index.html
[0.14]: ./spec/core/0.14/index.html
[0.13]: ./spec/core/0.13/index.html
#### Status-Legende
- :construction: **uncompleted**: noch in Arbeit befindliche Version
- :heavy_check_mark: **supported**: unterstützte Version
- :warning: **deprecated**: veraltete, aber unterstütze Version, die eine Warnung in jedem Response anzeigt
- :x: **unsupported**: nicht mehr unterstützte Version, die einen 406-Error zurückgibt
......
......@@ -5,10 +5,9 @@ HOST: https://api.youthweb.net
Dies ist die offizielle API von [youthweb.net](https://youthweb.net).
Aktuelle Version: 0.17 (2020-??-??)
Status: Beta
Version: 0.17 (2020-??-??)
- Developer Webseite: https://developer.youthweb.net
- Gitlab Repository: https://gitlab.com/youthweb/youthweb-api
- Github Mirror: https://github.com/youthweb/youthweb-api
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment