Confluence REST-API

Heute möchte ich dir die REST-API von Confluence vorstellen. Mit der REST-API hast du die Möglichkeit, aus einer anderen Anwendung heraus oder zum Beispiel mit einem Skript verschiedenste Dinge in Confluence zu tun, sodass du nicht alles von Hand erledigen musst.

Eine wichtige Sache, die dabei zu beachten ist: Die REST-API für die Server-/Data Center-Variante und für die Cloud unterscheiden sich. Für die Schnittstelle werden jeweils unterschiedliche Möglichkeiten geboten und teilweise andere Daten erwartet. Das Prinzip bei der Benutzung ist jedoch für beide gleich. Daher werde ich mich im Weiteren auf die Cloud-Variante konzentrieren.

Um die Anfragen an Confluence abzuschicken, benutze ich die Anwendung Postman. Diese ist kostenlos verfügbar und du kannst sie hier herunterladen.

Nachdem du die Anwendung gestartet hast, sollte es so bei dir aussehen.

Klickst du dann auf „Create Request“, kommst du in die Ansicht, um eine Anfrage an Confluence schicken zu können.

Als Erstes versuchen wir, alle Bereiche in Confluence anzeigen zu lassen. Dafür geben wir einmal die entsprechende URL ein.

In diesem Fall ist das https://neustaps-test.atlassian.net/wiki/rest/api/space. Dabei ist der Teil https://neustaps-test.atlassian.net/ die URL deiner Confluence-Instanz. Den Teil danach bekommst du aus der Doku zur REST-API. Diese verlinke ich dir am Ende des Artikels.

Zusätzlich musst du noch deine Log-in-Daten angeben. Gehe dazu in den Reiter „Authorization“ und wähle in dem Drop-Down-Feld „Basic Auth“ aus. Dann gibst du deinen Benutzernamen an. Für das Passwort kannst du nicht dein normales Passwort benutzen, sondern musst dir ein sogenanntes API-Token erzeugen. Dies machst du hier.

Danach musst du nur noch auf „Send“ klicken und im besten Fall bekommst du dann das Ergebnis der Abfrage im unteren Bereich angezeigt.

Der Status rechts oben zeigt dir an, ob die Anfrage erfolgreich war (Status 200) oder nicht (ein anderer Status).

Im Reiter „Body“ findest du das Ergebnis der Anfrage. Hier siehst du eine Liste der Bereiche, für die dein Benutzer berechtigt ist. Sollte die Anfrage nicht erfolgreich gewesen sein, findest du hier eine kurze Info, was schief gegangen ist.

In diesem Fall ist das nur ein Bereich, der „Project: Bastian Test“ heißt. Zusätzlich gibt es noch ein paar weitere Infos, zum Beispiel zur Homepage des Bereichs.

{
    "results": [
        {
            "id": 65539,
            "key": "BT",
            "name": "Project: Bastian Test",
            "type": "global",
            "status": "current",
            "_expandable": {
                "settings": "/rest/api/space/BT/settings",
                "metadata": "",
                "operations": "",
                "lookAndFeel": "/rest/api/settings/lookandfeel?spaceKey=BT",
                "identifiers": "",
                "permissions": "",
                "icon": "",
                "description": "",
                "theme": "/rest/api/space/BT/theme",
                "history": "",
                "homepage": "/rest/api/content/65610"
            },
            "_links": {
                "webui": "/spaces/BT",
                "self": "https://neustaps-test.atlassian.net/wiki/rest/api/space/BT"
            }
        }
    ],
    "start": 0,
    "limit": 25,
    "size": 1,
    "_links": {
        "base": "https://neustaps-test.atlassian.net/wiki",
        "context": "/wiki",
        "self": "https://neustaps-test.atlassian.net/wiki/rest/api/space"
    }
}

Du kannst nicht nur Dinge aus Confluence abfragen, sondern auch Daten an Confluence senden. Zur Übung erstellst du nun eine Seite in diesem Confluence-Bereich. Diese soll wiederum unter der Startseite des Bereichs angelegt werden. Dafür sind ein paar Stellen anzupassen oder zu ergänzen.
Zunächst einmal ist die URL anzupassen, da du nun auf den Content zugreifst. Des Weiteren musst du die Methode von „GET“ zum Lesen der Daten auf „POST“ zum Senden der Daten umstellen. Ganz wichtig: Im Reiter „Body“ sind die Informationen anzugeben, die an Confluence geschickt werden sollen. Hier muss zusätzlich als Art „raw“ und für das Format „JSON“ eingestellt werden.

Hier siehst du den kompletten Text des Bodys. Dies ist eine sehr minimalistische Variante. Wir geben hier nur den Titel, den Typ (also Seite oder Blog), den Bereich, den Status, die übergeordnete Seite und den Inhalt an.

{  "title": "Eine per REST API erzeugte Seite",
  "type": "page",
  "space": {
    "key": "BT"
  },
  "status": "current",
  "ancestors": [
    {
      "id": "65610"
    }
  ],
  "body": {
    "storage": {
      "value": "Hallo Welt. Dies ist ein Test.",
      "representation": "storage"
    }
  }
}

Als Ergebnis bekommen wir dann einige Infos zu der angelegten Seite. Und auch im Confluence ist die Seite nun zu sehen.

Neben dem Erstellen von Seiten können diese zum Beispiel auch aktualisiert und es können Kommentare erstellt werden. Sämtliche Möglichkeiten findest du in der Doku zur REST-API.
An einigen Stellen wird die ID einer Seite benötigt. Diese ist zum Beispiel beim Erstellen der Seite als „Ancestor“, also als übergeordnete Seite, notwendig. An diese ID kommst du, indem du dir die Seiteneigenschaften in Confluence anzeigen lässt. Dafür musst du im „…“-Menü auf erweiterte Details und dann auf Seiteninformationen klicken.

Nun weißt du, wie du Informationen aus Confluence per REST-API auslesen oder auch in Confluence schreiben kannst.

Hier sind wie versprochen die Links zur Dokumentation für die REST-API:
Für die Cloud: https://developer.atlassian.com/cloud/confluence/rest/intro/
Für Server/Data Center: https://docs.atlassian.com/ConfluenceServer/rest/7.11.0/

Habt ihr Fragen oder Anmerkungen? In der kommenden Woche zeige ich euch das Ganze auch für JIRA REST API.