From fa8343fa527a8402e118136cfa15160e44361e1d Mon Sep 17 00:00:00 2001 From: Martin Konitzer Date: Thu, 15 Aug 2019 18:03:13 +0200 Subject: [PATCH] [Feature - Ereignisse zum Antrags Auslesbar machen] Version 1.2.0 PR: https://github.com/europace/baufismart-ereignisse-api/pull/8 Trello: https://trello.com/c/wOqwWvMl/1944-soll-ereignisse-api-soll-ereignisse-am-antrag-liefern --- README.md | 54 +++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 41 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 382757d..b75077f 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,9 @@ # Baufismart Ereignisse-API -Die Ereignisse-API liefert die Ereignisse eines Vorgangs inkl. Zeitpunkt, Typ, Ersteller, Text und ggf. verlinkter Dokumente zurück. +Die Ereignisse-API liefert die Ereignisse eines Vorgangs bzw. eines Antrags inkl. Zeitpunkt, Typ, Ersteller, Text und ggf. verlinkter Dokumente zurück. # Dokumentation -*Aktuelle Version: 1.1.0 +*Aktuelle Version: 1.2.0 Die API ist vollständig in Swagger definiert und steht im YAML-Format zur Verfügung. Für die Generierung eines Clients empfehlen wir Swagger Codegen. @@ -12,22 +12,50 @@ Die API ist vollständig in Swagger definiert und steht im YAML-Format zur Verf ### API Docs -[API Docs](https://ereignisse-api-11.api-docs.io/1.0/ereignisse/) +[API Docs](https://ereignisse-api-12.api-docs.io/1.2.0/ereignisse/) + +## Wichtigste Features + +Ereignisse zu einem Vorgang auslesen. Beispiel: + +``` +curl -X GET \ + 'https://api.europace.de/v1/ereignisse/DM2902' \ + -H 'Authorization: Bearer eyJj...GVkA' \ + -H 'X-TraceID: myTest123' \ + -H 'cache-control: no-cache' +``` + +Ereignisse zu einem Vorgang auslesen. Beispiel: -## First Steps -Beispiel ``` curl -X GET \ - 'https://api.europace.de/v1/ereignisse?vorgangsNummer=DM2902' \ + 'https://api.europace.de/v1/ereignisse/DM2902/1/1' \ -H 'Authorization: Bearer eyJj...GVkA' \ -H 'X-TraceID: myTest123' \ - -H 'cache-control: no-cache' + -H 'cache-control: no-cache' ``` -### Authenifizierung -Für das Nutzen der API ist ein gültiger Europace JWT-Token erforderlich, der als Bearer-Token im HTTP-Header=Authorization mitgegeben wird (siehe Beispiel). -Wie man sich einen JWT-Token erstellt, erfährst du hier: -[europace2-api/PEX-SSO-API.md at master · hypoport/europace2-api · GitHub](https://github.com/hypoport/europace2-api/blob/master/Partnermanagement/PEX-SSO-API.md) +### Authentifizierung + +Die Authentifizierung läuft über den [OAuth2](https://oauth.net/2/) Flow vom Typ *ressource owner password credentials flow*. +https://tools.ietf.org/html/rfc6749#section-1.3.3 + +##### Credentials +Um die Credentials zu erhalten, erfragen Sie beim Helpdesk der Plattform die Zugangsdaten zur Auslesen API, bzw. bitten Ihren Auftraggeber dies zu tun. + +##### Schritte +1. Absenden eines POST Requests auf den [Login-Endpunkt](https://htmlpreview.github.io/?https://raw.githubusercontent.com/hypoport/antraege-auslesen-api/master/Dokumentation/index.html#_oauth2) mit Username und Password. Der Username entspricht der PartnerId und das Password ist der API-Key. Alternativ kann ein Login auch über einen GET Aufruf mit HTTP Basic Auth auf den Login-Endpunkt erfolgen. +2. Aus der JSON-Antwort das JWToken (access_token) entnehmen +3. Bei weiteren Requests muss dieses JWToken als Authorization Header mitgeschickt werden. + +##### Beispiel Implementierung für die Authentifizierung mit einem Java Client und Retrofit + +Den API client nicht mit dem Default Konstruktor, sondern dem credentials Kontruktor erzeugen. Z.B: + +``` + api = new ApiClient("oauth2","partnerID", "api-key").createService(AntraegeApi.class); +``` -### Parameter -* vorgangsNummer +## Fragen und Anregungen +Bei Fragen und Anregungen entweder ein Issue in GitHub anlegen oder an [helpdesk@europace2.de](mailto:helpdesk@europace2.de) schreiben. \ No newline at end of file