Various examples

In this section you will find utilization example of REST routes.

POST /artifacts

Here an example of artifact created with some artifact typed links:

Note

“values” sent are the same for POST /artifacts and PUT artifacts/{id}

{
  "tracker": {
    "id": 81
  },
  "values": [
    {
      "field_id": 1796,
      "value": "test"
    },
    {
      "field_id": 1809,
      "links": [
        {"id": 122, "type": "_is_child"},
        {"id": 123, "type": "custom"}
      ]
    }
  ]
}

Retrieve artifact attachment

The following javascript snippet shows how we can retrieve the content of an artifact, find a suitable file field and retrieve its first attachment. Assuming that the file is an image, this can be run in the console of a recent browser like Chrome or Firefox (don’t forget to update the base url, file id, and credentials).

(() => {
  const base_url = "https://tuleap.example.com/api/v1";
  const artifact_id = 1;
  const access_key =
    "tlp-k1-22.3329b8ac4401eaf03cf7776d6bab1809883624eef7a2e2dd2dc4d07696d32504";

  async function downloadImage() {
    const artifact = await getArtifact(artifact_id);
    const file_html_url = getFirstFileHTMLURL(artifact);
    saveTheFileSomewhere(file_html_url);
  }

  async function getArtifact(artifact_id) {
    console.log(`getArtifact (artifact_id = ${artifact_id})`);
    const init = {
      method: "GET",
      headers: new Headers({
        "Content-type": "application/json",
        "X-Auth-AccessKey": access_key
      }),
      mode: "cors"
    };
    const response = await fetch(`${base_url}/artifacts/${artifact_id}`);
    return response.json();
  }

  function getFirstFileHTMLURL(artifact) {
    const field = findFirstValidFileField(artifact);
    if (typeof field === "undefined") {
      throw new Error(
        "There are no attachments on this artifact (or you don't have permission to read them)."
      );
    }
    return field.file_descriptions[0].html_url;
  }

  const findFirstValidFileField = artifact =>
    artifact.values.find(isValidFileField);

  const isValidFileField = field =>
    field.type === "file" && fileHasAnAttachment(field);

  const fileHasAnAttachment = field => field.file_descriptions.length > 0;

  function saveTheFileSomewhere(file_html_url) {
    // For the demo, instead of saving the file, we display it in the browser
    const img = new Image();
    img.src = file_html_url;

    console.log("Attaching the image element at the end of the body");
    document.body.appendChild(img);
    console.log("done");
  }

  downloadImage();
})();

POST /svn

Repository creation and settings definition can be done in REST API.

{
   "project_id": 122,
   "name" : "repo01",
   "settings": {
     "commit_rules": {
       "is_reference_mandatory": true,
       "is_commit_message_change_allowed": false
     }
}

PUT /svn/{id}

When you update an artifact you must provide all settings, for instance if you want to allow commit message change you should provide following information to the route:

{
  "settings": {
    "commit_rules": {
      "is_reference_mandatory": true ,
      "is_commit_message_change_allowed": true
    },
    "immutable_tags": {
      "paths": [],
      "whitelist": []
    },
    "access_file": "",
    "email_notifications": []
  }
 }

DELETE /artifacts/{id}

Delete the corresponding artifact.

Some rule are specific to this route:

• only trackers administrators can delete artifacts

• there is a limitation of how many artifacts you can delete by day (sliding windows of 24h)

• limit is set by platform administrators and is common for all projects

• if plugin archive deleted items is enabled, XML is archived

POST /projects

Here an example of the payload used to create a public project:

{
  "shortname": "string",
  "description": "string",
  "label": "string",
  "is_public": true,
  "allow_restricted": true,
  "template_id": 101,
  "categories": [
      {
      "category_id": 1,
      "value_id": 2
      }
  ],
  "fields": [
      {
      "field_id": 1,
      "value": "My custom value"
      }
  ]
}