HIN Client API. Technische Schnittstelle. Version: 1.0 Datum: Status: Final

Transkript

1 HIN Client API Technische Schnittstelle Version: 1.0 Datum: Status: Final Health Info Net AG (HIN) Pflanzschulstrasse Winterthur support@hin.ch Tel

2 Inhaltsverzeichnis 1 Einleitung Ziele bei der Schnittstellendefinition Ziel des Dokuments Zielpublikum des Dokuments Literaturverzeichnis / referenzierte Dokumente Verwendete Abkürzungen Nutzungsbestimmungen Grundsatz Eigentumsrechte Verwendung der Schnittstelle Schnittstellenspezifikation Überblick Allgemeine Informationen Funktion «HIN Client Status abfragen» Funktion «Identität abfragen» Funktion «Alle Identitäten abfragen» Funktion «Aktive Identität abfragen» Funktion «Aktive Identität setzen» Funktion «Aktuelle Loginsession invalidieren» Anhang Kontakt und Support Änderungsnachweis HIN Client API-Schnittstelle Seite 2/17

3 1 Einleitung HIN ist die grösste ehealth Plattform der Schweiz. Die PKI gesicherte Plattform ermöglicht den sicheren und datenschutzkonformen Austausch von Informationen und Zugriff auf Applikationen. Weitere aktuelle Informationen entnehmen Sie bitte der Webseite Damit eine einfache Integration von anderen Applikationen mit dem HIN Client möglich ist, wird eine offene auf Standards basierende Schnittstelle (HIN Client API = Application Programming Interface) angeboten, mit der der Status des HIN Clients und die vorhandenen Identitäten abgefragt werden können. Darüber hinaus kann man die aktive Identität setzen oder einen Logout anfordern. 1.1 Ziele bei der Schnittstellendefinition Die Client API Schnittstelle: erlaubt die Kontrolle des HIN Client kann von Drittanwendungen einfach benutzt werden ist technologieunabhängig 1.2 Ziel des Dokuments Dieses Dokument beschreibt die HIN Client API und die einzelnen Funktionen davon, insbesondere: eine Übersicht welche Operationen und Abfragen unterstützt werden. eine Beschreibung wie die Requests und Responses aussehen. eine Darstellung wie Fehler gehandhabt werden. Das Dokument dient zur Sicherstellung eines einheitlichen Verständnisses und als Referenz für die Anbindung von Applikationen an den HIN Client über das Client API. 1.3 Zielpublikum des Dokuments Das Dokument richtet sich an die folgenden Personenkreise: Software-Hersteller und -Entwickler von Anwendungen für das Gesundheitswesen, die von den sicheren Kommunikationsmöglichkeiten über die HIN Plattform profitieren und aus Ihren Applikationen heraus den HIN Client abfragen und steuern wollen. Hier im Besonderen an technische Projektleiter, Architekten und Softwareentwickler. 1.4 Literaturverzeichnis / referenzierte Dokumente HIN-interne Referenzdokumente Referenz Internetadresse / URL Dokument Version [HIN-1] [HIN-2] unter der Rubrik «Support Dienste», «Support», «Anleitungen» «HIN Client Handbuch» 1.0 User Quickguide «Client Update» - für Windows - für Mac 1.0 HIN Client API-Schnittstelle Seite 3/17

4 Weitere Informationen zum HIN Client können bei HIN unter Tel oder angefordert werden. Allgemeine Referenzdokumente Referenz Internetadresse / URL Dokument Version [1] Representational_State_Transfer [2] s/rfc2616/rfc2616.html Wikipedia, REST HTTP 1.1 Standard 1.5 Verwendete Abkürzungen Abkürzung Bedeutung HTTP Hypertext Transfer Protocol REST Representational State Transfer API Application Programming Interface URI Uniform Resource Identifier POP3 Post Office Protocol Version 3 SMTP Simple Mail Transfer Protocol HIN Client API-Schnittstelle Seite 4/17

5 2 Nutzungsbestimmungen 2.1 Grundsatz Die in diesem Dokument spezifizierte API-Schnittstelle stehen Schnittstellennutzern (z.b. Praxissoftware-Hersteller) im Umfeld von HIN für die Anbindung von Applikationen über den HIN Client kostenlos zur Nutzung zur Verfügung. Die Schnittstellen müssen unverändert, d.h. wie in diesem Dokument spezifiziert, eingesetzt werden. Alle anderen Nutzungs- und Verwendungszwecke - insbesondere anderweitige kommerzielle Nutzungen - sind untersagt. Allfällige Anfragen für weitere Verwendungen der Schnittstellen sind schriftlich an die HIN AG zu richten. 2.2 Eigentumsrechte Die Eigentumsrechte der vorliegenden HIN-API-Schnittstelle liegen bei der HIN AG. 2.3 Verwendung der Schnittstelle HIN behält sich das Recht vor die Schnittstelle zukünftigen Bedürfnissen anzupassen, wobei HIN bestrebt ist die Schnittstelle rückwärtskompatibel weiterzuentwickeln. HIN verpflichtet sich dabei, Änderungen (Release) und Erweiterungen (neue Versionen) auf der Website anzuzeigen und die Dokumentationen zu publizieren. Anregungen für die Weiterentwicklung der Schnittstellen werden von HIN gerne entgegengenommen (Tel , support@hin.ch). Das Release Management inklusive der Freigabe und der Kommunikation neuer Release und Versionen erfolgen durch HIN. Es liegt in der Verantwortung der Praxissoftware-Hersteller bzw. weiterer allfälliger Dritter sich über die jeweils aktuellste Version bei Health Info Net AG zu informieren. Es besteht auch die Möglichkeit sich registrieren zu lassen, um bei allfälligen Änderungen an der API- Schnittstelle aktiv informiert zu werden. Die Registrierung erfolgt mittels an support@hin.ch. HIN Client API-Schnittstelle Seite 5/17

6 3 Schnittstellenspezifikation 3.1 Überblick Der HIN Client stellt anderen Applikationen (Web Browser, Mailprogramm oder Applikationen von Drittanbietern) einen verschlüsselten Kanal (in Form eines HTTP Proxy) zur Verfügung, über den diese mit Server-Applikationen in der HIN Plattform sicher kommunizieren können. Im HIN Client kann gewählt werden, mit welcher Identität diese verschlüsselte Verbindung erzeugt wird. Die Identität bestimmt dabei, welches Zertifikat zur Authentisierung am Server verwendet wird. Der HIN Client unterstützt dabei mehrere Identitäten, wobei immer nur eine aktiv sein kann. Eine aktive Identität ist entweder authentisiert (gültige Passphrase wurde angegeben) oder nicht (noch keine oder ungültige Passphrase angegeben). Die Client API kann gemäss nachfolgender Tabelle verwendet werden mit den aufgeführten Funktionen. HIN Client API-Schnittstelle Seite 6/17

7 Funktion HIN Client Status abfragen Beschreibung Abfrage des Versionsstrings, Prüfung der Konnektivität und Abfrage der konfigurierten Portnummern (damit andere Applikationen herausfinden können, unter welchen Ports der HIN Client Proxy für HTTP, für POP3 und für SMTP erreichbar sind) Information zu einer bestimmten Identität abfragen Liefert die Identitätsinformation für die Identität mit dem übergebenen Loginnamen. Diese Identitätsinformation enthält den Loginnamen, den Kommentar, und ausserdem Flags, die angeben, ob diese Identität aktiv und authentisiert ist. Alle installierten Identitäten abfragen Liefert die Identitätsinformation (siehe oben) für alle installierten Identitäten. Information zur aktiven Identität abfragen Liefert die Identitätsinformation für die aktive Identität. Aktive Identität setzen Aktiviert die (durch den übergebenen Loginnamen) spezifizierte Identität. Über ein Flag kann gesteuert werden, ob der HIN Client sofort die Authentisierung dieser Identität (Eingabe der Passphrase durch den Benutzer) verlangen soll. Aktive authentisierte Identität abmelden Die aktive authentisierte Identität wird abgemeldet und ist danach nicht mehr authentisiert. HIN Client API-Schnittstelle Seite 7/17

8 3.2 Allgemeine Informationen Die Schnittstelle wendet die Design Prinzipien des Representational State Transfers (REST) an. Identitäten stehen als Ressourcen zur Verfügung. Jeder Ressource ist eine URI (Uniform Resource Identifier) zugeordnet. Auf diese URIs kann mit standardisierten HTTP Methoden (GET, POST) zugegriffen werden. Als Rückgabewerte werden standardisierte HTTP Response Codes verwendet. Die Ressourcen (Client-Status, Identitäten bzw. Listen von Identitäten) werden in einem XML-Format beschrieben. Hier ein grober Überblick, wie die Funktionen als REST-Schnittstelle umgesetzt sind. Details folgen in den detaillierten Spezifikationen in den folgenden Kapiteln (3.3 bis 3.8): Funktion Ressource Methode HIN Client Status abfragen /status GET Information zu einer bestimmten Identität abfragen /identities/{login} GET Alle installierten Identitäten abfragen /identities GET Information zur aktiven Identität abfragen /active_identity GET Aktive Identität setzen /active_identity POST Aktive authentisierte Identität abmelden, also die aktuelle Login-Session invalidieren /invalidate_session POST Vorbedingung Damit das Client API verwendet werden kann, muss der HIN Client korrekt installiert und aktiv sein. Der Drittapplikation muss der TCP Port bekannt sein, auf dem das Client API zur Verfügung gestellt wird ( :<port>). Der Defaultwert für diesen Port ist Wenn nicht der Defaultwert verwendet werden kann (z.b. in Terminalserverumgebungen), so kann der konfigurierte Wert im HIN Client GUI eingesehen werden oder mit der HIN Client Info Applikation ausgelesen werden. 1 Um die Anbindung für Drittapplikationen einfacher zu gestalten, wurde hier etwas von den REST-Konventionen abgewichen, und kein DELETE /current_session verwendet (würde eventuell einen zusätzlichen Implementierungsaufwand in der Anbindung bedeuten). HIN Client API-Schnittstelle Seite 8/17

9 Diese ist unter Windows über eine Umgebungsvariable zu finden und unter Mac OS über ein Script aufrufbar. Wird der entsprechende Parameter angegeben, wird auf stdout der Port des Client-API ausgegeben. Betriebssystem Windows Mac OS Aufruf %HIN_CLIENT_INFO% -clientapiport /usr/bin/hinclientinfo -clientapiport Zu beachten ist, dass, wenn dieser Befehl in Windows in der Command-Shell (cmd.exe) eingegeben wird, nur eine leere Zeile ausgegeben wird. Davon darf man sich nicht irritieren lassen die Ausgabe in stdout erfolgt trotzdem, aber erscheint (wegen Interna des HIN Client Launcher hinclient.exe) nicht in der Windows Konsole. Der Port wird aber trotzdem, wie oben beschrieben, auf stdout ausgegeben, wie sich durch folgenden Versuch zeigen lässt: Der HIN Client stellt weiter sicher, dass nur lokale TCP Verbindungen (vom gleichen PC) zugelassen werden Request Für einen Request werden zwei Teile benötigt, die HTTP Methode und dieuri. In dieser Schnittstelle werden folgende HTTP Methoden verwendet: GET Eine Ressource wird angezeigt. POST Eine Ressource wird geändert. Gemäss der HTTP Spezifikation [2] sind PUT und DELETE idempotent. Das heisst der Anlegevorgang bzw. der Löschvorgang kann im Zweifelsfall wiederholt werden. GET ist darüber hinaus sicher, was bedeutet, dass kein GET Request eine Änderung der Daten zur Folge haben darf. Die URI setzt sich zusammen aus der Adresse des Webservice Endpoints und der Adresse der Ressource. Endpoint Ressource /identities/hmuster URI Bei POST Requests können zusätzlich Daten im HTTP Body übermittelt werden. HIN Client API-Schnittstelle Seite 9/17

10 3.2.3 Response Die Antwort enthält einen Antwortcode und Daten (können leer sein). Der Antwortcode steht im HTTP Header und ist einer der folgenden standardisierten HTTP Response Codes. Bei erfolgreicher Ausführung wird der folgende Response Code zurückgegeben: 200 OK Die Anfrage wurde erfolgreich bearbeitet. Fehlerfälle werden durch folgende Response Codes abgedeckt: 400 BAD REQUEST Die Anfrage ist syntaktisch nicht korrekt. 403 FORBIDDEN Der Benutzer hat keine Berechtigung. 404 NOT FOUND Die Ressource existiert nicht. 405 METHOD NOT ALLOWED Die Ressource unterstützt diese Methode nicht. Im Client API zum Beispiel: DELETE /identities 500 INTERNAL SERVER ERROR Ein Fehler ist aufgetreten. Im Fehlerfall werden diese Fehlercodes zurückgegeben. Der HTTP Body enthält dann einen (technischen) Fehlertext. Dieser Fehlertext sollte aber nicht automatisiert weiterverarbeitet werden, sondern soll lediglich den Entwickler bei der Implementierung unterstützen. Zusätzlich gibt es noch den Fehlerfall, dass der HIN Client nicht läuft bzw. nicht unter dem angenommenen Port läuft. Diese Fehlerfälle erkennt die Drittapplikation dadurch, dass sie sich nicht mit dem entsprechenden Client API Port verbinden kann Format und Encoding Die Ressourcen sind im XML Format im HTTP Body enthalten (UTF-8 Encoding). Dabei wird folgendes Encoding für verschiedene Datentypen verwendet: Datentyp Werte String String, UTF-8 encoded, z.b. <comment>sekretariat Dr. Mustermann</comment> Boolean true oder false, z.b. <authenticated>false</authenticated> Integer Als String kodierte Zahlen, z.b. <httpport>5016</httpport> Auch Ressourcen bzw. Entitäten werden als XML-Dokumente übertragen. HIN Client API-Schnittstelle Seite 10/17

11 Eine Identität enthält z.b. die folgenden Attribute: Attribut Typ Bedeutung name String Loginname der Identität comment String Kommentar zu der Identität active Boolean Ist diese Identität aktiv? authenticated Boolean Ist diese Identität authentisiert? (ist nur möglich, wenn sie auch aktiv ist) So könnte zum Beispiel das Dokument der Identität mmuster3 aussehen: <identity> <name>mmuster3</name> <comment>sekretariat Dr. Mustermann</comment> <active>true</active> <authenticated>false</authenticated> </identity> 3.3 Funktion «HIN Client Status abfragen» Über diese Funktion kann der aktuelle Status des HIN Clients (ohne erneute Überprüfung) abgefragt werden. Die Statusinformation enthält die Versionsnummer des Clients und die momentane Konnektivität (ist über diesen Client die HIN ehealth Plattform erreichbar, oder ist dies z.b. aufgrund von Netzwerk- oder Konfigurationsproblemen momentan nicht möglich) Request HTTP Methode Ressource GET /status Parameter keine Response Antwort, falls Aufruf erfolgreich: Antwortcode 200 OK Daten HIN Client Status (Version in der Form in der Form major.minor.patch-build und Konnektivitätsflag) HIN Client API-Schnittstelle Seite 11/17

12 Connected = true, wenn Zugriff die Sicherheitsinfrastruktur möglich ist und eine nutzbare Identität vorhanden ist. Ports für den Zugriff der lokalen Applikation auf den HIN Client <status> <version> </version> <connected>true</connected> <httpport>5016</httpport> <pop3port>5019</pop3port> <smtpport>5018</smtpport> </status> Die in Kapitel aufgeführten Fehlercodes (bzw. Fehlerfälle) sind möglich. 3.4 Funktion «Identität abfragen» Über diese Abfrage liefert der HIN Client die Identität mit dem angegebenen Loginnamen. Da der Loginname innerhalb eines HIN-Clients eindeutig ist, liefert diese Abfrage maximal eine Identität als Ergebnis Request HTTP Methode Ressource GET /identities/{name} Parameter Parameter oblig. Typ Beschreibung name X String Loginname der Identität Bemerkung: Der name-parameter ist als REST-Parameter Teil der URL: GET /clientapi/identities/hmuster liefert die XML-Repräsentation der Identität hmuster Response Antwort, falls Aufruf erfolgreich: Antwortcode 200 OK Daten Identität mit diesem Loginnamen, z.b. <identity> <name>mmuster1</name> <comment>dr. Max Mustermann</comment> HIN Client API-Schnittstelle Seite 12/17

13 <active>true</active> <authenticated>true</authenticated> </identity> Alternative Antworten bzw. Antworten im Fehlerfall Response Codes Daten Beschreibung 404 NOT FOUND (Fehlertext) Es existiert keine Identität mit dem angegebenen Loginnamen. Die in Kapitel aufgeführten Fehlercodes (bzw. Fehlerfälle) sind ebenfalls möglich. 3.5 Funktion «Alle Identitäten abfragen» Diese Abfrage liefert eine Liste aller im HIN Client installierten Identitäten Request HTTP Methode Ressource GET /identities Parameter keine Response Antwort, falls Aufruf erfolgreich: Antwortcode 200 OK Eine Liste aller installierten Identitäten, z.b.: Daten <identities> <identity> <name>mmuster1</name> <comment>dr. Max Mustermann</comment> <active>true</active> <authenticated>true</authenticated> </identity> <identity> <name>mmuster2</name> <comment>frau Dr. Maria Mustermann</comment> <active>false</active> <authenticated>false</authenticated> </identity> <identity> <name>mmuster3</name> <comment>sekretariat Dr. Mustermann</comment> <active>false</active> <authenticated>false</authenticated> </identity> HIN Client API-Schnittstelle Seite 13/17

14 </identities> Alternative Antworten bzw. Antworten im Fehlerfall Diese Liste kann auch leer sein (wenn noch keine Identität installiert ist). Die in Kapitel aufgeführten Fehlercodes (bzw. Fehlerfälle) sind möglich. 3.6 Funktion «Aktive Identität abfragen» Diese Abfrage liefert die momentan aktive Identität zurück Request HTTP Methode Ressource GET /active_identity Parameter keine Response Antwort, falls Aufruf erfolgreich: Antwortcode 200 OK Die aktive Identität, z.b. Daten <identity> <name>mmuster1</name> <comment>dr. Max Mustermann</comment> <active>true</active> <authenticated>false</authenticated> </identity> Alternative Antworten bzw. Antworten im Fehlerfall Response Codes Daten Beschreibung 404 NOT FOUND (Fehlertext) Es ist momentan keine Identität aktiv. Dies kann z.b. passieren, wenn noch keine Identität installiert wurde. Die in Kapitel aufgeführten Fehlercodes (bzw. Fehlerfälle) sind ebenfalls möglich. 3.7 Funktion «Aktive Identität setzen» Dieser Aufruf aktiviert eine bestimmte (durch Loginnamen spezifizierte) Identität. HIN Client API-Schnittstelle Seite 14/17

15 3.7.1 Request HTTP Methode Ressource POST /active_identity Parameter Parameter oblig. Typ Beschreibung name String Der Loginname der Identität, die aktiviert werden soll authenticate Boolean Wenn authenticate=true übergeben wird, fordert der HIN Client den Benutzer auf, die Passphrase für die neu aktivierte Identität einzugeben. Achtung: Der Rückgabewert dieses Aufrufs gibt keine Information darüber, ob die Authentisierung erfolgreich war oder nicht, da die Authentisierung erst nach dem Aufruf ausgelöst wird. Beide hier aufgeführten Parameter werden als HTTP POST Parameter übergeben, z.b.: name=mmuster1&authenticate=false Response Antwort, falls Aufruf erfolgreich: Antwortcode 200 OK Die aktive Identität als XML-Dokument, z.b. Daten <identity> <name>mmuster1</name> <comment>dr. Max Mustermann</comment> <active>true</active> <authenticated>false</authenticated> </identity> Alternative Antworten bzw. Antworten im Fehlerfall Response Codes Daten Beschreibung 404 NOT FOUND (Fehlertext) Es existiert keine Identität mit dem HIN Client API-Schnittstelle Seite 15/17

16 angegebenen Loginnamen. Die in Kapitel aufgeführten Fehlercodes (bzw. Fehlerfälle) sind ebenfalls möglich. 3.8 Funktion «Aktuelle Loginsession invalidieren» Die aktuelle Loginsession wird invalidiert, wodurch eine eventuell authentisierte aktive Identität danach nicht mehr authentisiert ist (aber noch immer aktiv!). Der Benutzer muss die aktive Identität erneut authentisieren (wird vom HIN Client aufgefordert, die Passphrase einzugeben). Es ist dabei kein Fehlerfall, wenn die aktive Identität zur Zeit des Aufrufs nicht authentisiert ist Request HTTP Methode Ressource POST /invalidate_session Parameter keine Response Antwort, falls Aufruf erfolgreich: Antwortcode 200 OK Daten keine Die in Kapitel aufgeführten Fehlercodes (bzw. Fehlerfälle) sind möglich. HIN Client API-Schnittstelle Seite 16/17

17 4 Anhang 4.1 Kontakt und Support Bei Fragen zum Hin Client und der Nutzung der zugehörigen API-Schnittstelle kann man sich an den HIN Support wenden: Das Support Team kann unter: kontaktiert werden Telefonisch Unser Call-Desk-Team ist von Montag bis Freitag von für Sie da. Telefon Unsere MitarbeiterInnen informieren Sie gerne und vermitteln den Kontakt zu den zuständigen Fachpersonen Internet Unter findet man weitere Informationen über HIN 4.2 Änderungsnachweis Datum Ausgabe Änderung Seiten Freigabe des finalen Dokumentes für die externe Kommunikation alle HIN Client API-Schnittstelle Seite 17/17