REST-Interface Getting Started

Die technische Referenzdokumentation finden Sie auf Ihrer Projectile-Installation.

Dazu ändern Sie einfach die URL von “start” auf “rest”:

https://YOUR_SERVER/projectile/rest

Für die Entwicklung einer REST-Schnittstelle können Sie eine beliebige REST-Entwicklungsumgebung benutzen, zum Beispiel Postman: https://www.postman.com.

Für eine Benutzung der Schnittstelle müssen Sie sich Authentifizieren, siehe:

https://YOUR_SERVER/projectile/wiki/rest/authentication

Sie übermitteln also das Token als Authorization-Header mit dem Bearer-Prefix:

Damit ist ein Nutzer in Projectile durch die Anmeldung identifiziert.

Jetzt muss der Nutzer aber auch Rechte haben, die REST-Schnittstelle zu benutzen.

Dies ist hier beschrieben:

http://YOUR_SERVER/projectile/wiki/rest/credential

Sie können diese Rechte auf verschiedene Weise vergeben:

Sie deaktivieren die Rechteprüfung komplett. Dies ist zum Beispiel für ein Entwicklungssystem akzeptabel. Dazu müssen Sie in der Datei config/bsm.properties den Eintrag

bsm.rest.needCredential=false

einfügen und Projectile neu starten.

Sie geben ihrem angemeldeten Nutzer die Rechte. Dies wird in der Regel für REST-Zugriff benutzt, der eine Schnittstelle zu einem anderen System bildet. Der Nutzer, der hierfür verwendet wird, ist in der Regel kein normaler Projectile-Nutzer, der auch eine konkrete Person repräsentiert, sondern ein reiner REST-Nutzer.

Wenn Sie so einen Nutzer haben, können Sie diesen in der Projectile-Oberfläche den ACL-Eintrag unter:

Administration > Rechtesystem > ACL > credentials > RESTUser

zuweisen. Der Nutzer sollte dort als Owner eingetragen werden oder Mitglied einer REST-Benutzergruppe sein, die Sie unter Relatives oder Friends dem ACL-Eintrag zuweisen.

Sollte es diesen ACL-Eintrag noch nicht geben, dann können Sie diesen im Script-Interpreter von Projectile mit dem Script CreateRESTUserCredential.java anlegen. Am besten machen Sie das auch gleich mit dem REST-User, dann ist dieser automatisch Owner.

Sie verwenden Application-Keys. Dies wird in der Regel benutzt, wenn sich alle Mitarbeiter via REST in Projectile anmelden können sollen, dies aber über eine App oder ähnliches geschieht. Dann muss ein Application-Key generiert und in der App hinterlegt werden.

Sie können einen neuen Application-Key unter Administration > System > REST > Create REST application anlegen. Geben Sie Ihrer App eine frei gewählte ID und speichern Sie diese. Dann können Sie unter Aktionen mit “GenerateApplicationKey” einen neuen Key erzeugen.

Diesen kopieren Sie bitte und übermitteln diesen als Parameter XXXXXXXXXXXX - wie folgt - bei jedem Request:

x-application-key: XXXXXXXXXXXX

Jetzt können Sie auf die Daten Ihrer Projectile-Instanz zugreifen.

Laden Sie zum Beispiel eine Liste der Projekte mit einem GET-Request auf diese URL.

https://YOUR_SERVER/projectile/rest/api/json/0/projects

Beachten Sie, dass der Request die oben beschriebenen Header für Autorization und application-key enthält.

Alle zugreifbaren Daten finden Sie auch in der Referenzdokumentation unter “Modules & Entities”.

https://YOUR_SERVER/projectile/wiki/rest/index