Erste Schritte

docs/1_Getting_Started.md

@@ -2,19 +2,19 @@
 
 <!-- theme: info -->
 
-> ## ①
-> Registrieren Sie sich für einen Account, um einen Zugriff auf eine API zu bekommen. Im Rahmen der Registrierung bekommen Sie durch das System eine eindeutige ID (Beispiel-ID) mitgeteilt. Aus dieser Account-ID leiten sich mit einem entsprechenden Präfix die Sender-ID (Senderpräfix_Beispiel-ID) und Subscriber-ID (Subscriberpräfix_Beispiel-ID) ab. (Siehe [Link auf „Authentifizierung und Autorisierung“ Abschnitt / Unterseite für Registrierung eines Accounts])
+> ## ① Account registrieren
+> Registrieren Sie sich für einen Account, um einen Zugriff auf eine API zu bekommen. Im Rahmen der Registrierung bekommen Sie durch das System eine eindeutige ID (Beispiel-ID) mitgeteilt. Aus dieser Account-ID leiten sich mit einem entsprechenden Präfix die Sender-ID (Senderpräfix_Beispiel-ID) und Subscriber-ID (Subscriberpräfix_Beispiel-ID) ab. ➡ [Anwender Registrierung](./4_Authentifizierung_und_Autorisierung.md)
 
-> ## ②
-> Für den Zugriff auf die API fügen Sie dem Account einen Client hinzu und vergeben Sie dem Client die entsprechenden Scopes. (Siehe [Link auf „Authentifizierung und Autorisierung“ Abschnitt / Unterseite für Clientanlage und Scope Vergabe].
+> ## ② Client anlegen
+> Für den Zugriff auf die API fügen Sie dem Account einen Client hinzu und vergeben Sie dem Client die entsprechenden Scopes. ➡ [Client registrieren](./4_Authentifizierung_und_Autorisierung.md#client-registrierung)
 
-> ## ③
-> Für einen einfachen Einstieg zum Test der API können Sie folgende Postman Collection (Link auf die Collection) nutzen und mittels des Postman REST Clients die Anfragen an die API durchführen. (Für nähere Informationen zu Postman siehe https://www.postman.com/) Alternativ können Sie die Anfragen auch mittels eigener Anwendungen oder alternative REST Client durchführen. Falls Sie nur für die Sender oder Subscriber Seite entwickeln, nutzen sie den folgenden Vorschlag auf Basis Postman [Link auf Postman basierte Teststrategie als Unterseite von „Weiterführende Informationen“]. 
+> ## ③ API ausprobieren
+> Für einen einfachen Einstieg zum Test der API können Sie folgende Postman Collection (Link auf die Collection) nutzen und mittels des Postman REST Clients die Anfragen an die API durchführen. (Für nähere Informationen zu Postman siehe https://www.postman.com/) Alternativ können Sie die Anfragen auch mittels eigener Anwendungen oder alternative REST Client durchführen. Falls Sie nur für die Sender oder Subscriber Seite entwickeln, nutzen sie den folgenden Vorschlag auf Basis Postman ➡ [Testen mit Postman](./Detailinformationen/Postman.md)
 
-> ## ④
-> Für jede Anfrage an die API Endpunkte ist ein gültiger JWT-Token mit der Anfrage mitzusenden. Für nähere Informationen zum Abruf eines JWT-Token siehe [Link auf „Authentifizierung und Autorisierung“ Abschnitt / Unterseite für Token Abruf].
+> ## ④ OAuth Token abrufen
+> Für jede Anfrage an die API Endpunkte ist ein gültiger JWT-Token mit der Anfrage mitzusenden. Für nähere Informationen zum Abruf eines JWT-Token siehe ➡ [OAuth Details](./Detailinformationen/OAuth.md)
 
-> ## ⑤
+> ## ⑤ API nutzen
 > Verweis auf die Ablage der Open API Spec im Original
 > Abschließendes Beispiel eines API Abrufs mit Token Abruf und einem Beispiel unter Nutzung des Tokens.
 

docs/4_Authentifizierung_und_Autorisierung.md

@@ -46,7 +46,7 @@ Hier ein Beispiel einer solchen Email:
 > Mit freundlichem Gruß
 > Ihr FIT-Connect Team.
 
-## Client (Anwendung) Registrierung auf ein API
+## Client Registrierung
 
 <!-- theme: warning -->
 > **Hinweis:** Im Zuge der ersten Anmeldung empfehlen wir die Umstellung der Sprache auf Deutsch.
@@ -76,6 +76,10 @@ Nun erscheint der folgende Dialog:
 ![Token anfordern](https://raw.githubusercontent.com/fiep-poc/assets/master/images/oauth/09_request_token.png)
 
 Hier vergeben Sie einen Anwendungsnamen und eine Beschreibung. Die Angabe einer Umleitungs-URI ist optional.
+Haken Sie beiden APIs ("Source/Sender" und "Subscriber") an.
+
+<!-- theme: warning -->
+> **Achtung:** Zum Testen benötigen Sie Zugriff auf beide APIs. Achten Sie bitte darauf, im unteren Teil beide Haken zu setzen.
 
 Mit dem Button "Token anfordern" lösen Sie die Erstellung der Anwendung (Client) und der für Sie gültigen Subscriber-ID (subscriber-id) und/oder Source/Sender-ID (source-id) aus. Diese Subscriber-ID wird für alle weiteren API Aufrufe benötigt.
 
@@ -133,103 +137,3 @@ Verfahrensschritte:
 Wurden alle Prüfschritte erfolgreich absolviert, wird die Anfrage an den Zustelldienst übergeben.
 
 Nach Bearbeitung der Anfrage im Zustelldienst wird die Antwort des Zustelldienstes an den Client zurückgesendet.
-
-## Testverfahren mit dem Tool Postman
-
-Für Tests kann auch SoapUI oder jeder andere REST Client mit OAuth 2.0 Unterstützung eingesetzt werden.
-Unter diesen beiden Adressen können Sie eine Postman Collection und eine Postman Environment herunterladen:
-- [Collection](https://raw.githubusercontent.com/fiep-poc/assets/master/postman/FIT-Connect.postman_collection.json)
-- [Environment](https://raw.githubusercontent.com/fiep-poc/assets/master/postman/FIT-Connect.postman_environment.json)
-
-### API Aufruf mit Postman OAuth 2.0 Konfiguration
-
-Mit diesen Angaben können Sie das API z.B. via Postman nutzen. Dazu wählen sie zunächst den Bereich "Authorization" aus. Danach kann der Button "Get New Access Token" genutzt werden.
-
-![Authorization konfigurieren](https://raw.githubusercontent.com/fiep-poc/assets/master/images/oauth/14_authorization.png)
-
-![Token holen](https://raw.githubusercontent.com/fiep-poc/assets/master/images/oauth/15_request_token.png)
-
-![Use Token](https://raw.githubusercontent.com/fiep-poc/assets/master/images/oauth/16_use_token.png)
-
-Mit diesem Token kann das API erfolgreich aufgerufen werden.
-
-![API Aufruf](https://raw.githubusercontent.com/fiep-poc/assets/master/images/oauth/17_api_call.png)
-
-In diesem Beispiel wurde eine neue Destination angelegt.
-
-### API Aufruf mit wget
-
-Sie können auch mit dem Kommandozeilentool "wget" testen. In diesem Beispiel wird die Liste aller Destinations abgerufen:
-
-```bash
-wget --quiet --output-document - \
-  --method GET \
-  --timeout=0 \
-  --header 'Accept: application/json' \
-  --header 'Authorization: Bearer 5eadf042ef434913a5724d5e5ce38bc0' \
-   'https://subscriber.fiep-poc.de/beta6/subscriber-c94ae37e-dcc5-345e-a530-8651bdfa5f2c/destinations'
-```
-
-### Manueller OAuth 2.0 Fluss
-
-Ein Entwickler hat in der Regel keine OAuth 2.0 Funktion direkt zur Verfügung. Daher müssen die Schritte einzeln durchgeführt werden. Um Zugriff auf die APIs zu erhalten muss Ihr Client zuerst einen OAuth Zugriff machen, um mit “client_id“, “client_secret“ ein Zugriffs-Token zu erhalten.
-
-Die URL für den OAuth Zugriff lautet:
-https://oauth.fiep-poc.de/invoke/pub.apigateway.oauth2/getAccessToken
-
-Folgende Query Parameter sind dabei mitzugeben:
-- grant_type:	client_credentials (fix)
-- client_id: c1bbee16-fae1-4dc1-b0c6-b75a02b359b0 (Beispiel)
-- client_secret:	91e7f6dd-5567-456f-a8be-aac10237c4c8 (Beispiel)
-- scope: subscriber-c94ae37e-dcc5-345e-a530-8651bdfa5f2c:manage (Beispiel)
-
-<!-- theme: warning -->
-> **Hinweis zu den Token:**
-> Für den Zugriff auf die beiden APIs sind zwei unterschiedliche Scopes erforderlich. Diese enthalten beide Ihre Anwender-ID und könnten beispielsweise wie folgt aussehen:
-> - Für die Application Subscriber API: **subscriber-**c94ae37e-dcc5-345e-a530-8651bdfa5f2c:manage
-> - Für die Application Sender API: **sender-**c94ae37e-dcc5-345e-a530-8651bdfa5f2c:manage
-> 
-> Sie können beim holen des Access Token das richtige Scope einsetzen oder ein Token für beide Scopes/APIs beziehen. Dazu schreiben Sie beide Scopes mit einem Leerzeichen dazwischen hintereinander:
-> 
-> `subscriber-c94ae37e-dcc5-345e-a530-8651bdfa5f2c:manage sender-c94ae37e-dcc5-345e-a530-8651bdfa5f2c:manage`
-> 
-> ![Zwei Scopes](https://raw.githubusercontent.com/fiep-poc/assets/master/images/oauth/18_zwei_scopes.png)
-> 
-> Bitte beachten Sie, dass Sie statt "c94ae37e-dcc5-345e-a530-8651bdfa5f2c" Ihre Anwender-ID einsetzen müssen.
-
-Ein Aufruf mit dem Werkzeug "wget" sieht z.B. wie folgt aus:
-
-```bash
-wget --quiet --output-document - \
-  --method GET \
-   'https://oauth.fiep-poc.de/invoke/pub.apigateway.oauth2/getAccessToken?grant_type=client_credentials&client_id=c1bbee16-fae1-4dc1-b0c6-b75a02b359b0&client_secret=91e7f6dd-5567-456f-a8be-aac10237c4c8&scope=subscriber-c94ae37e-dcc5-345e-a530-8651bdfa5f2c:manage'
-```
-
-Alternativ kann der Request auch per POST durchgeführt werden:
-
-```bash
-wget --quiet --output-document - \
-  --post-data 'grant_type=client_credentials&client_id=c1bbee16-fae1-4dc1-b0c6-b75a02b359b0&client_secret=91e7f6dd-5567-456f-a8be-aac10237c4c8&scope=subscriber-c94ae37e-dcc5-345e-a530-8651bdfa5f2c:manage' \
-  'https://oauth.fiep-poc.de/invoke/pub.apigateway.oauth2/getAccessToken'
-```
-
-Die Antwort sieht in etwa wie folgt aus:
-
-```json
-{
-  "access_token": "0bd226153b394d209a9d57bd7a42ee70",
-  "token_type": "Bearer",
-  "expires_in": 3600
-}
-```
-
-Der Wert für "access_token" wird dann als Header Parameter "Authorization" zusammen mit dem Text "Bearer" verwendet.
-
-Hier wieder ein Beispiel mit dem Tool "wget":
-
-```bash
-wget --quiet --output-document - \
-  --method GET \
-  --header 'Authorization: Bearer 0bd226153b394d209a9d57bd7a42ee70' \
-   'https://subscriber.fiep-poc.de/beta6/subscriber-c94ae37e-dcc5-345e-a530-8651bdfa5f2c/destinations'
-```

docs/Detailinformationen/OAuth.md

+# OAuth Details
+
+## API Aufruf mit wget
+
+Sie können auch mit dem Kommandozeilentool "wget" testen. In diesem Beispiel wird die Liste aller Destinations abgerufen:
+
+```bash
+wget --quiet --output-document - \
+  --method GET \
+  --timeout=0 \
+  --header 'Accept: application/json' \
+  --header 'Authorization: Bearer 5eadf042ef434913a5724d5e5ce38bc0' \
+   'https://subscriber.fiep-poc.de/beta6/subscriber-c94ae37e-dcc5-345e-a530-8651bdfa5f2c/destinations'
+```
+
+## Manueller OAuth 2.0 Fluss
+
+Ein Entwickler hat in der Regel keine OAuth 2.0 Funktion direkt zur Verfügung. Daher müssen die Schritte einzeln durchgeführt werden. Um Zugriff auf die APIs zu erhalten muss Ihr Client zuerst einen OAuth Zugriff machen, um mit “client_id“, “client_secret“ ein Zugriffs-Token zu erhalten.
+
+Die URL für den OAuth Zugriff lautet:
+https://oauth.fiep-poc.de/invoke/pub.apigateway.oauth2/getAccessToken
+
+Folgende Query Parameter sind dabei mitzugeben:
+- grant_type:	client_credentials (fix)
+- client_id: c1bbee16-fae1-4dc1-b0c6-b75a02b359b0 (Beispiel)
+- client_secret:	91e7f6dd-5567-456f-a8be-aac10237c4c8 (Beispiel)
+- scope: subscriber-c94ae37e-dcc5-345e-a530-8651bdfa5f2c:manage (Beispiel)
+
+<!-- theme: warning -->
+> **Hinweis zu den Token:**
+> Für den Zugriff auf die beiden APIs sind zwei unterschiedliche Scopes erforderlich. Diese enthalten beide Ihre Anwender-ID und könnten beispielsweise wie folgt aussehen:
+> - Für die Application Subscriber API: **subscriber-**c94ae37e-dcc5-345e-a530-8651bdfa5f2c:manage
+> - Für die Application Sender API: **sender-**c94ae37e-dcc5-345e-a530-8651bdfa5f2c:manage
+> 
+> Sie können beim holen des Access Token das richtige Scope einsetzen oder ein Token für beide Scopes/APIs beziehen. Dazu schreiben Sie beide Scopes mit einem Leerzeichen dazwischen hintereinander:
+> 
+> `subscriber-c94ae37e-dcc5-345e-a530-8651bdfa5f2c:manage sender-c94ae37e-dcc5-345e-a530-8651bdfa5f2c:manage`
+> 
+> ![Zwei Scopes](https://raw.githubusercontent.com/fiep-poc/assets/master/images/oauth/18_zwei_scopes.png)
+> 
+> Bitte beachten Sie, dass Sie statt "c94ae37e-dcc5-345e-a530-8651bdfa5f2c" Ihre Anwender-ID einsetzen müssen.
+
+Ein Aufruf mit dem Werkzeug "wget" sieht z.B. wie folgt aus:
+
+```bash
+wget --quiet --output-document - \
+  --method GET \
+   'https://oauth.fiep-poc.de/invoke/pub.apigateway.oauth2/getAccessToken?grant_type=client_credentials&client_id=c1bbee16-fae1-4dc1-b0c6-b75a02b359b0&client_secret=91e7f6dd-5567-456f-a8be-aac10237c4c8&scope=subscriber-c94ae37e-dcc5-345e-a530-8651bdfa5f2c:manage'
+```
+
+Alternativ kann der Request auch per POST durchgeführt werden:
+
+```bash
+wget --quiet --output-document - \
+  --post-data 'grant_type=client_credentials&client_id=c1bbee16-fae1-4dc1-b0c6-b75a02b359b0&client_secret=91e7f6dd-5567-456f-a8be-aac10237c4c8&scope=subscriber-c94ae37e-dcc5-345e-a530-8651bdfa5f2c:manage' \
+  'https://oauth.fiep-poc.de/invoke/pub.apigateway.oauth2/getAccessToken'
+```
+
+Die Antwort sieht in etwa wie folgt aus:
+
+```json
+{
+  "access_token": "0bd226153b394d209a9d57bd7a42ee70",
+  "token_type": "Bearer",
+  "expires_in": 3600
+}
+```
+
+Der Wert für "access_token" wird dann als Header Parameter "Authorization" zusammen mit dem Text "Bearer" verwendet.
+
+Hier wieder ein Beispiel mit dem Tool "wget":
+
+```bash
+wget --quiet --output-document - \
+  --method GET \
+  --header 'Authorization: Bearer 0bd226153b394d209a9d57bd7a42ee70' \
+   'https://subscriber.fiep-poc.de/beta6/subscriber-c94ae37e-dcc5-345e-a530-8651bdfa5f2c/destinations'
+```

docs/Detailinformationen/Postman.md

+# Testen mit Postman
+
+Für Tests kann auch SoapUI oder jeder andere REST Client mit OAuth 2.0 Unterstützung eingesetzt werden.
+Unter diesen beiden Adressen können Sie eine Postman Collection und eine Postman Environment herunterladen:
+- [Collection](https://raw.githubusercontent.com/fiep-poc/assets/master/postman/FIT-Connect.postman_collection.json)
+- [Environment](https://raw.githubusercontent.com/fiep-poc/assets/master/postman/FIT-Connect.postman_environment.json)
+
+## API Aufruf mit Postman OAuth 2.0 Konfiguration
+
+Mit diesen Angaben können Sie das API z.B. via Postman nutzen. Dazu wählen sie zunächst den Bereich "Authorization" aus. Danach kann der Button "Get New Access Token" genutzt werden.
+
+![Authorization konfigurieren](https://raw.githubusercontent.com/fiep-poc/assets/master/images/oauth/14_authorization.png)
+
+![Token holen](https://raw.githubusercontent.com/fiep-poc/assets/master/images/oauth/15_request_token.png)
+
+![Use Token](https://raw.githubusercontent.com/fiep-poc/assets/master/images/oauth/16_use_token.png)
+
+Mit diesem Token kann das API erfolgreich aufgerufen werden.
+
+![API Aufruf](https://raw.githubusercontent.com/fiep-poc/assets/master/images/oauth/17_api_call.png)
+
+In diesem Beispiel wurde eine neue Destination angelegt.

docs/Weiterführende Informationen/OAuth.md

-# OAuth Details

docs/Weiterführende Informationen/Postman.md

-# Testen mit Postman