Integration per API

Vorteile der API-Anbindung gegenüber einer Anbindung via Java Script Snipped

Die Anbindung einer Karriereseite über eine API bietet einige Vorteile im Vergleich zu einem JavaScript-Snippet:

Flexibilität und Kontrolle: APIs ermöglichen eine direkte Kommunikation zwischen Ihrer Website und dem Backend-System (z. B. concludis).

Sie haben mehr Kontrolle über die Datenübertragung und können spezifische Endpoints nutzen, um Bewerbungen zu verarbeiten, Stellenanzeigen anzuzeigen und Bewerberdaten zu übertragen.

Sicherheit: APIs verwenden standardisierte Protokolle wie HTTP/HTTPS und JSON. Im Gegensatz dazu kann JavaScript-Snippets anfälliger für Sicherheitslücken sein, da sie auf der Client-Seite ausgeführt werden.

Dokumentation: APIs bieten klare Dokumentationen, die den Entwicklungsprozess erleichtern. Sie können spezifische Endpoints, Parameter und Authentifizierungsmethoden nachschlagen1.

Mehrsprachigkeit: Über APIs können Sie mehrsprachige Inhalte abrufen, indem Sie separate Abfragen für verschiedene Sprachen erstellen.

Testing: Sie können die API-Anbindung über ein Staging-System testen, bevor Sie sie in der Live-Umgebung einsetzen.

Insgesamt bietet die API-Integration mehr Flexibilität, Sicherheit und Kontrolle über Ihre Karriereseite im Vergleich zu JavaScript-Snippets.

Leitfaden zur Anbindung der Karriereseite via API

concludis stellt zur Integration der Stellenbörse in die Unternehmenshompage eine Rest-API zur Verfügung. Diese ist unter der URL https://api.concludis.de erreichbar. Für den Zugriff ist die Einrichtung eines Benutzerkontos erforderlich. Bitte wenden Sie sich hierzu an unseren Support.

Project-Endpoint

Gibt eine Liste von Projekten zurück.

Aufruf-Schema

Get: https://api.concludis.de/{username}/1.0/DE/project/{pid}/{board}/{group1}/{group2}/{group3}/{locationgroup}/{location}(?(limit={limit})(&offset={offset})(&filter_intext={filter_intext})(&filter_jb={filter_jb})(&radius_zip={radius_zip})(&radius_km={radius_km}))

URI-Parameter

string {username}

Benutzername für den API-Zugriff auf Ihre Installation. Dieser wird Ihnen bei Einrichtung Ihres Accounts mitgeteilt.

string{pid}

Dieser Parameter bestimmt grundsätzlich die Art des Rückgabewertes Ihrer Anfrage.

Mögliche Werte:

FULL Die Antwort erfolgt detailliert, also mit sämtilichen verfügbaren Projekt-Attributen.

SLIM Die Antwort erfolgt in Kurzform, also nur mit einigen wichtigen Projekt-Attributen die wesentlich für eine Listenansicht sind.

COUNT Die Antwort beinhaltet lediglich die Gesamtzahl der gefundenen Ergebnisse.

{project-id} Wird eine beliebige Projekt-ID übergeben, so enthält das Resultat lediglich das entsprechende Projekt mit sämtlichen verfügbaren Projekt-Attributen (FULL).

string{board}

Dieser Parameter ermöglicht die Filterung nach Stellenbörse.

Mögliche Werte:

ALL Dieser Wert bewirkt, dass die Filterung nach Stellenbörse ausgesetzt wird.

({board-id}(,{board-id}(,...))) Es können eine oder mehrere Stellenbörsen-IDs (getrennt mit Komma) übergeben werden. Das Resultat liefert somit alle Projekte, die mindestens einer der gelisteten Stellenbörsen zugeordnet sind.

string{group1}

Dieser Parameter ermöglicht die Filterung nach Stellengruppe1.

Mögliche Werte:

ALL Dieser Wert bewirkt, dass die Filterung nach Stellengruppe1 ausgesetzt wird.

({group1-id}(,{group1-id}(,...))) Es können eine oder mehrere Stellengruppen1-IDs (getrennt mit Komma) übergeben werden. Das Resultat liefert somit alle Projekte, die mindestens einer der gelisteten Stellengruppe1 zugeordnet sind.

string{group2}

Dieser Parameter ermöglicht die Filterung nach Stellengruppe2.

Mögliche Werte:

ALL Dieser Wert bewirkt, dass die Filterung nach Stellengruppe2 ausgesetzt wird.

({group2-id}(,{group2-id}(,...))) Es können eine oder mehrere Stellengruppen2-IDs (getrennt mit Komma) übergeben werden. Das Resultat liefert somit alle Projekte, die mindestens einer der gelisteten Stellengruppe2 zugeordnet sind.

string{group3}

Dieser Parameter ermöglicht die Filterung nach Stellengruppe3.

Mögliche Werte:

ALL Dieser Wert bewirkt, dass die Filterung nach Stellengruppe3 ausgesetzt wird.

({group3-id}(,{group3-id}(,...))) Es können eine oder mehrere Stellengruppen3-IDs (getrennt mit Komma) übergeben werden. Das Resultat liefert somit alle Projekte, die mindestens einer der gelisteten Stellengruppe3 zugeordnet sind.

string {locationgroup}

Dieser Parameter ermöglicht die Filterung nach Standortgruppen.

Mögliche Werte:

ALL Dieser Wert bewirkt, dass die Filterung nach Standortgruppen ausgesetzt wird.

({locationgroup-id}(,{locationgroup-id}(,...))) Es können eine oder mehrere Standortgruppen-IDs (getrennt mit Komma) übergeben werden. Das Resultat liefert somit alle Projekte, die mindestens einer der gelisteten Standortgruppen zugeordnet sind.

string{location}

Dieser Parameter ermöglicht die Filterung nach Standort.

Mögliche Werte:

ALL Dieser Wert bewirkt, dass die Filterung nach Standort ausgesetzt wird.

({location-id}(,{location-id}(,...))) Es können eine oder mehrere Standort-IDs (getrennt mit Komma) übergeben werden. Das Resultat liefert somit alle Projekte, die mindestens einer der gelisteten Standorte zugeordnet sind.

GET-Parameter

int {limit}

Begrenzt die Anzahl der maximal zurückgelieferten Ergebnisse. Der Wert 0 liefert alle Ergebnisse.

Default-Wert: 0

int {offset}

Gibt an, ab dem wievielten Datensatz mit der Ausgabe begonnen werden soll. Dieser Parameter wird nur berücksichtigt, wenn der Parameter {limit} angegeben wurde.

Default-Wert: 0

string {filter_intext}

Legt fest, ob nur Interne, nur Externe oder alle Projekte zurückgegeben werden. Das Verhalten dieses Parameters ist abhängig vom Parameter {filter_jb}. Enthält {filter_jb} den Wert 1, so werden sämtliche Kriterien, die für die Sichtbarkeit des Projekts in der Stellenbörse verantwortlich sind angewendet. Berücksichtigt also die Projekteinstellungen "In Stellenliste anzeigen", die jeweilige Projektlaufzeit sowie die automatischer Heruntername nach Ablauf der Projektlaufzeit. Enthält {filter_jb} den Wert 0, so wird lediglich berücksichtigt, ob das Projekt grundsätzlich für die Interne bzw. Externe Veröffentlichung vorgesehen ist (Wert: i oder e).

Mögliche Werte:

a Dieser Wert liefert sowohl für die interne als auch die externe Veröffentlichung vorgesehene Projekte.

i Dieser Wert liefert nur für die interne Veröffentlichung vorgesehene Projekte.

e Dieser Wert liefert nur für die externe Veröffentlichung vorgesehene Projekte.

Default-Wert: a

int {filter_jb}

Legt fest, ob die für die Sichtbarkeit des Projekts in der Stellenbörse verantwortlichen Kriterien angewendet werden sollen. Berücksichtigt also die Projekteinstellungen "In Stellenliste anzeigen", die jeweilige Projektlaufzeit sowie die automatischer Heruntername nach Ablauf der Projektlaufzeit.

Mögliche Werte:

0 deaktiviert

1 aktiviert

Default-Wert: 0

int {radius_km}

Radius in Kilometern für die Umkreissuche. Wird nur berücksichtigt, wenn auch {radius_zip} angegeben wird.

Werden {radius_zip} und {radius_km} angegeben, so werden nur Projekte zurückgeliefert, die Standorten zugewiesen wurden die geografisch nicht weiter vom Zentrum {radius_zip} entfernt sind als die angegebene Distanz {radius_km}.

string {radius_zip}

Postleitzahl des Zentrums für die Umkreissuche. Wird nur berücksichtigt, wenn auch {radius_km} angegeben wird.

Integration in Ihre Unternehmenswebsite

Der oben beschriebene Project-Endpoint kann abgefragt werden, um auf Ihrer Unternehmenswebsite eine vollständig individualisierte Stellenbörse zu erzeugen.

Abfragen auf den Project-Endpoint sind nur von Server zu Server zugelassen. Ihr Server sollte den Endpoint in regelmäßigen Abständen abfragen, die Ergebnisse zwischenspeichern und die individualisierte Stellenbörse sowie die Detaildarstellung der Jobs lediglich aus dem internen Cache darstellen. Eine Abfrage durch den Browser des Besuchers der Stellenbörse via XMLHttpRequest ist nicht zulässig. Zum einen müssten dem Browser bei diesem Vorgehen die API-Zugangsdaten mitgeteilt werden, zum anderen führt dies, je nach Frequentierung ihrer Stellenbörse schnell zu einer sehr großen Anzahl von API-Anfragen. Bitte fragen Sie die API also serverseitig ab, cachen Sie das Ergebnis severseitig und führen Sie etwaige XMLHttpRequests gegen Ihren eigenen Server durch, der dann auf den lokalen cache zugreift. Es existiert bereits eine von concludis selbst entwickelte, auf PHP basierende Client-Library, die bereits die Abfragealgorithmen implementiert, und einen lokalen Cache auf MySql-Basis füllt. Zur Unterstützung können Sie unter hier auf den Link der Git-Library zugreifen.

Deeplinking

Wenn Sie eine eigene Stellenbörse implementieren, so werden Sie vermutlich eine völlig individuelle URL-Struktur aufbauen. Für die Veröffentlichung von Jobs aus concludis heraus wird jedoch immer zwingend die concludis URL publiziert. Um dem Besucher beim Aufruf dieser URL die entsprechende Job-Darstellung auf Ihrer Unternehmenswebsite (Deeplink) zu präsentieren, muss dieser von concludis auf die entsprechende Unterseite Ihrer Internetpräsenz weitergeleitet werden.

In concludis kann zu diesem Zweck eine globale Weiterleitungs-URL für die Stellenbörse, die Stellenanzeige als auch für das Bewerbungsformular definiert werden. Diese Konfigurationsmaske finden Sie unter Einstellungen > Systemeinstellungen > Reiter "Stellenbörse":

Bitte tragen Sie hier die entsprechenden Ziel-URLs Ihrer Website ein. Hierbei haben Sie die Möglichkeit, gewisse dynamische Parameter zu übermitteln. Für die Internationalisierung stehen hier die Parameter [lang] und [locale] zur Verfügung. Für das interne Deeplink-Routing auf Ihrer Website können Sie zusätzlich die Parameter [jobid] und [location_external_id] verwenden. Letztere ist jedoch nur im Rahmen von sehr speziellen Integrationen erforderlich.

Wie Sie anhand der Konfigurationsmöglichkeiten feststellen werden, ist für diese Weiterleitung auf die Stellenanzeige und das Bewerbungsformular ein einheitliches URL-Schema im Zielsystem erforderlich. Dieses URL-Schema muss zwingend die concludis Job-ID berücksichtigen!

Sollte dies aufgrund des URL-Konzepts Ihrer Website nicht vorhanden sein, so muss auf dem Zielsystem ein URL-Path-Mapping implementiert werden, das einen beliebigen Deeplink, der die concludis Job-ID beinhaltet, auf die entsprechende interne URL weiterleitet. Im folgenden Beispiel wird ein realistischer Fall geschildert, um das Vorgehen zu veranschaulichen:

Struktur der Unternehmenswebsite

https://www.example.com/karriere/job/full-stack-developer-m-f-x

(Stellenanzeige zu dem aus der API abgerufenen Job mit der concludis Job-ID #165. Die interne URL basiert auf dem Stellentitel.)

https://www.example.com/karriere/job/senior-project-manager-m-f-x

(Stellenanzeige zu dem aus der API abgerufenen Job mit der concludis Job-ID #197. Die interne URL basiert auf dem Stellentitel.)

Hierbei handelt es sich um eine nicht-einheitliche URL-Struktur. Es gibt keine sinnvolle Ziel-URL, die im concludis System als Weiterleitungsziel hinterlegt werden könnte. Aus diesem Grunde ist es erforderlich auf dem Ziel-System ein URL-Path-Mapping in Form einer Weiterleitung zu definieren. Die wäre z.B. durch folgende Weiterleitungen möglich:

https://www.example.com/karriere/job/165 > https://www.example.com/karriere/job/full-stack-developer-m-f-x

https://www.example.com/karriere/job/197 > https://www.example.com/karriere/job/senior-project-manager-m-f-x

Im concludis System würde dann die folgende (einheitliche) Ziel-URL hinterlegt werden:

https://www.example.com/karriere/job/[jobid]

Durch die auf der Unternehmenswebsite eingerichteten Weiterleitungen führen die URLs nun immer zum gewünschten Ziel.