JIRA REST-API

Heute möchte ich dir die Jira REST-API vorstellen. In diesem Beitrag habe ich dir bereits die REST-API von Confluence und die Grundlagen, wie du die REST-API benutzt, vorgestellt.

Auch bei Jira ist es so, dass sich die API für die Server-/Data Center-Variante und für die Cloud unterscheiden. Wenn du dich im Server- oder Data Center-Umfeld bewegst, solltest du darauf achten, die Doku für die richtige Version auszuwählen. Denn die API unterscheidet sich bei den verschiedenen Versionen von Jira. Die Doku für die beiden APIs ist wieder am Ende dieses Artikels verlinkt.

In Jira kannst du vieles mit der REST-API erledigen: Relativ naheliegend sind alle Aktivitäten rund um die Vorgänge. Auf diesen Bereich werde ich gleich noch näher eingehen. Zudem kannst du dir Informationen zu Projekten anzeigen lassen, oder – soweit du die Berechtigung dazu hast – Projekte erstellen oder Änderungen an Projekten vornehmen, wie zum Beispiel Benutzerrollen hinzufügen. Ein konkreter Anwendungsfall hierfür wäre beispielsweise die Projekterstellung zu automatisieren.

Nun geht es genauer um die Vorgänge. Ich starte in der Cloud-Variante mit dem einfachen Fall, dass ich mir die Informationen aus einem Vorgang ansehen möchte.

Hierzu kann die folgende URL verwendet werden: https://neustaps-test.atlassian.net/rest/api/3/issue/BROW-4 – wobei https://neustaps-test.atlassian.net die Cloud-Instanz ist und „/rest/api/3/issue/BROW-4“ der Aufruf der REST-API. „BROW-4“ ist der Schlüssel des Vorgangs, den ich mir ansehen möchte.

Das Ergebnis ist sehr lang, da hier unter anderem alle benutzerdefinierten Felder enthalten sind. Daher lasse ich einige Abschnitte weg, um es etwas übersichtlicher zu halten. Wie du siehst, sind hier die ganzen Systemfelder wie „fixversions“ und „priority“ enthalten. Diese lassen sich leicht über den Namen identifizieren. Bei den benutzerdefinierten Feldern ist das etwas schwieriger, da diese nur über die ID identifiziert werden können. Wenn du dazu mehr wissen möchtest, lies gerne unseren Artikel zu benutzerdefinierten Feldern.

Bei einigen Feldern werden weitere Informationen mitgeliefert: So wird zum Beispiel bei der Priorität nicht nur der Name, sondern auch die ID und die URL des Symbols angezeigt. Andere Felder, die viele Informationen liefern, sind unter anderem der Status und die Benutzerfelder wie „Creator/Reporter“ oder „Assignee“.

{
    "expand": "renderedFields,names,schema,operations,editmeta,changelog,versionedRepresentations",
    "id": "16842",
    "self": "https://neustaps-test.atlassian.net/rest/api/3/issue/16842",
    "key": "BROW-4",
    "fields": {
        "statuscategorychangedate": "2020-11-22T16:01:02.954+0100",
        "fixVersions": [],
        "customfield_11200": null,
        "resolution": null,
        "customfield_11201": null,
        "customfield_11202": null,
        "customfield_11203": null,
        "customfield_10500": null,
        "customfield_10501": null,
        "customfield_10503": null,
        "customfield_10900": null,
        "customfield_10506": null,
        "lastViewed": null,
    ....
        "priority": {
            "self": "https://neustaps-test.atlassian.net/rest/api/3/priority/3",
            "iconUrl": "https://neustaps-test.atlassian.net/images/icons/priorities/major.svg",
            "name": "Schwer",
            "id": "3"
        },
    ....
        "timeestimate": null,
        "aggregatetimeoriginalestimate": null,
        "versions": [],
        "issuelinks": [],
        "assignee": null,
        "status": {
            "self": "https://neustaps-test.atlassian.net/rest/api/3/status/10210",
            "description": "",
            "iconUrl": "https://neustaps-test.atlassian.net/images/icons/status_generic.gif",
            "name": "Zu erledigen",
            "id": "10210",
            "statusCategory": {
                "self": "https://neustaps-test.atlassian.net/rest/api/3/statuscategory/2",
                "id": 2,
                "key": "new",
                "colorName": "blue-gray",
                "name": "Zu erledigen"
            }
        },
    ....
        "creator": {
            "self": "https://neustaps-test.atlassian.net/rest/api/3/user?accountId=557058%3A3d24f480-3824-4e1f-9242-52e841ecdaf4",
            "accountId": "557058:3d24f480-3824-4e1f-9242-52e841ecdaf4",
            "avatarUrls": {
                "48x48": "https://secure.gravatar.com/avatar/580b516560bf54035a1340b514ee3d00?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FAG-4.png",
                "24x24": "https://secure.gravatar.com/avatar/580b516560bf54035a1340b514ee3d00?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FAG-4.png",
                "16x16": "https://secure.gravatar.com/avatar/580b516560bf54035a1340b514ee3d00?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FAG-4.png",
                "32x32": "https://secure.gravatar.com/avatar/580b516560bf54035a1340b514ee3d00?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FAG-4.png"
            },
            "displayName": "Alana Grant",
            "active": true,
            "timeZone": "Europe/Berlin",
            "accountType": "atlassian"
        },
        "subtasks": [],
        "customfield_12101": null,
        "reporter": {
            "self": "https://neustaps-test.atlassian.net/rest/api/3/user?accountId=557058%3A3d24f480-3824-4e1f-9242-52e841ecdaf4",
            "accountId": "557058:3d24f480-3824-4e1f-9242-52e841ecdaf4",
            "avatarUrls": {
                "48x48": "https://secure.gravatar.com/avatar/580b516560bf54035a1340b514ee3d00?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FAG-4.png",
                "24x24": "https://secure.gravatar.com/avatar/580b516560bf54035a1340b514ee3d00?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FAG-4.png",
                "16x16": "https://secure.gravatar.com/avatar/580b516560bf54035a1340b514ee3d00?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FAG-4.png",
                "32x32": "https://secure.gravatar.com/avatar/580b516560bf54035a1340b514ee3d00?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FAG-4.png"
            },
            "displayName": "Alana Grant",
            "active": true,
            "timeZone": "Europe/Berlin",
            "accountType": "atlassian"
        },
        "aggregateprogress": {
            "progress": 0,
            "total": 0
        },
    ....
        "issuetype": {
            "self": "https://neustaps-test.atlassian.net/rest/api/3/issuetype/6",
            "id": "6",
            "description": "Eine Sammlung ähnlicher Bugs, Stories und Tasks.",
            "iconUrl": "https://neustaps-test.atlassian.net/secure/viewavatar?size=medium&avatarId=10607&avatarType=issuetype",
            "name": "Epic",
            "subtask": false,
            "avatarId": 10607
        },
        "timespent": null,
        "project": {
            "self": "https://neustaps-test.atlassian.net/rest/api/3/project/11902",
            "id": "11902",
            "key": "BROW",
            "name": "Web Browser App",
            "projectTypeKey": "software",
            "simplified": false,
            "avatarUrls": {
                "48x48": "https://neustaps-test.atlassian.net/secure/projectavatar?avatarId=10803",
                "24x24": "https://neustaps-test.atlassian.net/secure/projectavatar?size=small&s=small&avatarId=10803",
                "16x16": "https://neustaps-test.atlassian.net/secure/projectavatar?size=xsmall&s=xsmall&avatarId=10803",
                "32x32": "https://neustaps-test.atlassian.net/secure/projectavatar?size=medium&s=medium&avatarId=10803"
            }
        },
    ....
        "customfield_10014": " Basic trip booking",
        "timetracking": {},
    ....
    }
}

Aus dieser Antwort kannst du die für dich notwendigen Informationen heraussuchen und weiterverwenden.

Nun ist es an der Zeit, den Status des Vorgangs zu verändern. Dafür nimmst du wieder den Vorgang „BROW-4“. Dieser sieht im Jira so aus:

Du passt nun im Postman die Abfrage für Jira an: Zum einen die Methode von „GET“ zu „POST“ und zum anderen die URL – hier musst du ein „/transitions“ anhängen.

Zusätzlich brauchst du wieder einen Body. Hier gibst du erstmal nur den Parameter „transitions“ und die ID des Statusübergangs an. Diese ID findest du heraus, indem du den Workflow bearbeitest und dir die Eigenschaften des Statusübergangs anzeigen lässt. Dann steht in der URL die ID mit drin.

Wenn du diese Anfrage jetzt ausführst, dann ändert sich der Status des Vorgangs von „zu erledigen“ zu „Done“.

Du kannst hier nicht nur den Status ändern, sondern auch Felder angeben, die ausgefüllt werden sollen, wenn der Statusübergang eine Bildschirmmaske beinhaltet. Außerdem kannst du einen Kommentar hinzufügen.

Als Nächstes eröffnest du den Vorgang wieder und fügst einen Kommentar hinzu, warum du dies tust. Der Kommentar ist in einem speziellen Format hinzuzufügen, was wiederum die Lesbarkeit stark reduziert. Aber in der Regel machst du sowas aus einer Anwendung oder einem Skript heraus, sodass die geringere Lesbarkeit nicht so stark ins Gewicht fällt.

So sieht der Body jetzt aus:

{
   "transition": {
    "id": "11"
  },
   "update": {
    "comment": [
      {
        "add": {
          "body": {
            "type": "doc",
            "version": 1,
            "content": [
              {
                "type": "paragraph",
                "content": [
                  {
                    "text": "Funktioniert leider noch nicht.",
                    "type": "text"
                  }
                ]
              }
            ]
          }
        }
      }
    ]
  }
}

Wichtig ist, dass dem Übergang eine entsprechende Maske zugeordnet ist, in der ein Kommentar gesetzt werden kann. Sonst wird der Kommentar hier einfach ignoriert. Das Ergebnis sieht dann so aus:

Als Letztes zeige ich dir das Anhängen eines neuen Anhangs per API. Diesmal sind ein paar mehr Stellen anzupassen.

Zum einen musst du wieder die URL anpassen: Du ersetzt „/transitions“ durch „/attachments“. Zusätzlich ergänzt du im Reiter „Headers“ noch das Attribut „X-Atlassian-Token“ und den Wert „no-check“.

Beim Body wechselst du in den Modus „form-data“ und trägst dort als Key „file“ ein. Dies kannst du auch als Typ auswählen, sodass du eine Datei aussuchen kannst, die du übertragen möchtest.

Wenn du dies nun abschickst, wird die Datei an den Vorgang angehängt.

So weit so gut. Wenn du noch Fragen hast, melde dich gerne über die Kommentare unter dem Beitrag.

Hier findest du die Dokus:
Server/Data Center:
Jira Software: https://docs.atlassian.com/software/jira/docs/api/REST/8.5.12/
Jira Service Management: https://docs.atlassian.com/jira-servicedesk/REST/4.15.0/
Cloud:https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/