Various examples

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

POST /artifacts

Note

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

With a step definitions field

The steps are ordered according the rank field. A step can be added or removed by adding or removing an entry in the value array.

{
  "tracker": {
    "id": 81
  },
  "values": [
    [
      {
        "field_id": 10162,
        "type": "ttmstepdef",
        "label": "steps",
        "value": [
          {
            "description": "Click on the link",
            "description_format": "commonmark",
            "expected_results": "The page should open",
            "expected_results_format": "commonmark",
            "rank": 1
          },
          {
            "description": "Search for the image on the page",
            "description_format": "commonmark",
            "expected_results": "An image is present on the page",
            "expected_results_format": "commonmark",
            "rank": 2
          }
        ]
      }
    ],
  ]
}

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"
      }
  ]
}