====== REST-Interface Getting Started ======

Die technische Referenzdokumentation finden Sie auf Ihrer Projectile-Installation.

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

<file>
https://YOUR_SERVER/projectile/rest
</file>

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

===== Authentifizierung =====

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

<file>
https://YOUR_SERVER/projectile/wiki/rest/authentication
</file>

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

{{:module:bearer.png?800|}}

Damit ist ein Nutzer in Projectile durch die Anmeldung identifiziert. 


===== Zugriff auf REST-Schnittstelle =====

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

Dies ist hier beschrieben: 

<file>
http://YOUR_SERVER/projectile/wiki/rest/credential
</file>

Sie können diese Rechte auf verschiedene Weise vergeben:

==== A) Entwicklungsserver ohne Rechteprüfung ====

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

<file>
bsm.rest.needCredential=false
</file>

einfügen und Projectile neu starten.

==== B) Spezieller REST-User ====

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:

<file>
Administration > Rechtesystem > ACL > credentials > RESTUser
</file>

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.

==== C) Application Keys ====

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:

<file>
x-application-key: XXXXXXXXXXXX
</file>

{{:module:application-keys.png?800|}}

===== Zugriff auf die Daten =====

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.

<file>
https://YOUR_SERVER/projectile/rest/api/json/0/projects
</file>

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".

<file>
https://YOUR_SERVER/projectile/wiki/rest/index
</file>