Zum Hauptinhalt springen

inriva API Dokumentation

Verfasst von Jochen Ritscher

API URL

Die API kann je nach Umgebung unter der URL erreicht werden:

https://meinefirma.production.inriva.com/api/v2

API Dokumentation

Die API Dokumentation für unsere Plattform ist unter

/api-docs

abrufbar und ist nach REST aufgebaut. Wir verwenden Swagger, um die Dokumentation übersichtlich und benutzerfreundlich zu gestalten.

API Version

Die aktuell unterstützte Version der API ist Version V2.

Beispiel Anwendungsfälle

  • Abrufen der Bewerberliste

  • Synchronisieren von CRM-Kontaktdaten

  • Auflisten der aktuellen Stellenbeschreibungen

Authentifizierung mit Token

Um unsere API nutzen zu können, ist eine Authentifizierung mit einem Token erforderlich. Dieser Token muss vom Benutzer erstellt werden, indem er auf seinem Benutzerkonto auf den Tab "API" klickt und dort "Zugangsschlüssel erstellen" auswählt.

Nachdem der Token erstellt wurde, kann er für die Verwendung der API genutzt werden.

Beispiel:

GET https://meinefirma.production.inriva.com/v2/contacts HTTP/1.1
Authorization: Bearer mExQVpm76FpVEx9fpaW9fctT

Hinweis: Die in Version 1 der API verwendete Basic-Authentifizierung wird nicht mehr unterstützt

Verwendung der API mit dem integrierten Client

Um die API zu nutzen, muss der Token in das Swagger-Format eingegeben werden. Dies kann entweder manuell erfolgen oder durch die Verwendung von Tools wie Postman.

Im Swagger-Format sind alle verfügbaren Methoden und Endpunkte aufgelistet. Durch die Eingabe des Tokens können diese Methoden aufgerufen und die gewünschten Aktionen ausgeführt werden.

Es ist wichtig, dass der Token bei jeder Anfrage mitgesendet wird, um eine erfolgreiche Authentifizierung zu gewährleisten. In der API Dokumentation klicken Sie hierzu auf "Authorize" und geben den generierten Token im Feld bearerAuth ein.

Grundsätzlich arbeiten wir mit REST und JSON. Dabei folgen wir dem Ruby on Rails Pattern:

HTTP Verb

Path

Used for

GET

/contacts

display a list of all contacts

POST

/contacts

create a new contact

GET

/contacts/:id

display a specific contact

PATCH

/contacts/:id

update a specific contact

DELETE

/contacts/:id

delete a specific contact

Alle API werden auf Basis der OpenAPI Spezifikation 3.0.3 dokumentiert und beschrieben.

Pagination

API Pagination

Die API verwendet eine Pagination. Das bedeutet, dass die API die Ergebnisse einer Anfrage in mehrere Seiten aufteilt, um die Datenmenge zu reduzieren und die Ladezeiten zu verbessern.

Um die Pagination zu nutzen, müssen Sie die entsprechenden Parameter in Ihrer Anfrage angeben. Die wichtigsten Parameter sind

limit

und

offset

Mit limit können Sie die maximale Anzahl an Ergebnissen pro Seite festlegen, während offset angibt, ab welchem Ergebnis die API die Daten zurückgeben soll.

Wenn Sie beispielsweise eine Anfrage mit

limit=10

und

offset=20

senden, erhalten Sie die Ergebnisse 21 bis 30. Wenn Sie keine Parameter angeben, verwendet die API standardmäßig einen

limit

-Wert von 25 und einen

offset

-Wert von 0.

Um die Anzahl der verfügbaren Seiten zu ermitteln, können Sie den Header

X-Total-Count

auslesen, der die Gesamtzahl der Ergebnisse enthält. Mit dieser Information können Sie dann die Pagination in Ihrer Anwendung entsprechend gestalten.

Es ist wichtig zu beachten, dass die API möglicherweise nicht alle Ergebnisse auf einmal zurückgibt, sondern diese in mehreren Seiten aufteilt. Daher sollten Sie Ihre Anfragen entsprechend anpassen, um alle gewünschten Daten zu erhalten.

Me-Endpunkt

Der "Me"-Endpunkt gibt die verfügbaren Daten des eigenen Benutzers zurück.

Fazit

Die Verwendung des Swagger-Formats ermöglicht eine einfache und übersichtliche Nutzung unserer API. Durch die Authentifizierung mit einem Token wird die Sicherheit der Daten gewährleistet. Bei Fragen oder Problemen mit der API stehen wir Ihnen gerne unter support@inriva.com zur Verfügung.

Changelog

  • 01.05.2024 API V2 freigegeben

Hat dies Ihre Frage beantwortet?