REST API

Полная документация по REST API доступна в разделе "Справочник разработчика"


В справочнике разработчика выберите интересующую сущность и на дополнительной панели справа будет представлен полный перечень атрибутов, с их характеристиками, примеры запросов REST API, пример возвращаемых данных, объектная модель и примеры написания PHP-скриптов для автоматизации.

Аутентификация

Для использования REST API в каждом запросе необходимо передавать HTTP-заголовок с ключом:

'Devprom-Auth-Key': 'a806f6e2af139ea856db981c20278865'

Для получения ключа необходимо открыть профиль пользователя (меню на аватарке пользователя) и перейти в раздел "Ключи".


При необходимости сбросить ключ на новое значение используйте соответствующую кнопку:

Примеры использования

Из консоли

# curl -X POST -H "Devprom-Auth-Key: a806f6e2af139ea856db981c20278865" -H "Content-Type:application/json" https://demo.myalm.ru/pm/support/api/v1/issues -d '{"Caption":"test123"}'

Под Windows:

# curl -X POST -H "Devprom-Auth-Key: a806f6e2af139ea856db981c20278865" -H "Content-Type:application/json" https://demo.myalm.ru/pm/support/api/v1/issues -d "{\"Caption\":\"test123\"}"


Управление требованиями

Создание документа требований

curl -X POST -H "Devprom-Auth-Key:f14acb09aa3b63cd8608fdf4ccb6d355" -H "Content-Type:application/json" http://devprom.local/pm/clementine/api/latest/requirement/items -d @reqs-doc.json

Содержимое reqs-doc.json:

{
   "Caption":"Requirements document",
   "IsDocument":1
}

Создание раздела документа требований

curl -X POST -H "Devprom-Auth-Key:f14acb09aa3b63cd8608fdf4ccb6d355" -H "Content-Type:application/json" http://devprom.local/pm/clementine/api/latest/requirement/items -d @chapter-doc.json

Содержимое chapter-doc.json:

{
   "Caption":"Chapter requirement",
   "Content":"Requirement content",
   "ParentPage":{
      "Id":Requirement.Id
   }
}

где:

  • Requirement.Id - Id документа требований или родительского требования.

Создание одиночного требования с определенным типом

curl -X POST -H "Devprom-Auth-Key:f14acb09aa3b63cd8608fdf4ccb6d355" -H "Content-Type:application/json" http://devprom.local/pm/clementine/api/latest/requirement/items -d @reqs.json

Содержимое reqs.json:

{
   "Caption":"Requirement",
   "Content":"Description",
   "PageType":{
      "Id":RequirementType.Id
   }
}

где:

  • RequirementType.Id - Id типа требований.

Создание требования с изображением в тексте

curl -X POST -H "Devprom-Auth-Key:f14acb09aa3b63cd8608fdf4ccb6d355" -H "Content-Type:application/json" http://devprom.local/pm/clementine/api/latest/requirement/items -d @reqs.json

Содержимое reqs.json:

{
   "Caption":"Requirement",
   "Content":"<p><img alt=\"\" src=\"data:image\/jpeg;base64,\/9j\/4AAQSkZJRgABAQEAeAB4AAD\/4QAiRXhpZgAATU0AKgAAAAgAAQESAAMAAAABAAEAAAAAAAD\/2wBDAAIBAQIBAQICAgICAgICAwUDAwMDAwYEBAMFBwYHBwcGBwcICQsJCAgKCAcHCg0KCgsMDAwMBwkODw0MDgsMDAz\/2wBDAQICAgMDAwYDAwYMCAcIDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAz\/wAARCAAyADIDASIAAhEBAxEB\/8QAHwAAAQUBAQEBAQEAAAAAAAAAAAECAwQFBgcICQoL\/8QAtRAAAgEDAwIEAwUFBAQAAAF9AQIDAAQRBRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAkM2JyggkKFhcYGRolJicoKSo0NTY3ODk6Q0RFRkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKjpKWmp6ipqrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6\/8QAHwEAAwEBAQEBAQEBAQAAAAAAAAECAwQFBgcICQoL\/8QAtREAAgECBAQDBAcFBAQAAQJ3AAECAxEEBSExBhJBUQdhcRMiMoEIFEKRobHBCSMzUvAVYnLRChYkNOEl8RcYGRomJygpKjU2Nzg5OkNERUZHSElKU1RVVldYWVpjZGVmZ2hpanN0dXZ3eHl6goOEhYaHiImKkpOUlZaXmJmaoqOkpaanqKmqsrO0tba3uLm6wsPExcbHyMnK0tPU1dbX2Nna4uPk5ebn6Onq8vP09fb3+Pn6\/9oADAMBAAIRAxEAPwD92Phx8WPDPxh8PSap4V17SfEGnw3MllLPYXSTrBcRHbLA+0nZKh4aNsMp4IBrpK+Uf21fhjq37NfjKb9pD4ZWNx\/behwxn4i+H7LasfjzQYQfMdoiVVtRs490lvPlZCivCxdGWOvpTwH440n4meC9J8RaDfQ6pouuWcOo6feRZ8u6t5UDxyLkA4ZWB5557Vy0azc3SqK0l+K7r9ez9U3x4fEOVSVGorSWvk09mvya6Pyab2qKM4orqOwKKKCcGgAopvmr\/eFFADZYw0bZCkEYIPQivwZ0T\/go58Uv+CT\/AMd\/iN8JPA194d8RfD3wr4p1C20nR9bt5LuHTYTcuwSGWN45I2KkB1LNGJPMYJuZi37gfGv4r6Z8DPhD4o8aaw2NL8KaVc6tdAHDOkMbSFV\/2m27QOpJAAJNfy1eMPGWpfELxfq3iDWrhbrWvEN9Pql\/OBt8+4nkaWZwPd3Y\/jX53x5mk8IqDw8nGpd6rtpdPum7fcflPidnFXArDvCzcat5O6\/l0un3Tdvu8j9V\/h\/\/AMHPqFIYvFnwdkjZVxJc6P4jEnmH1EMsC7R7GVq9Ktf+Dmf4LtbL5\/gT4uRy4+ZY7HTJEB9mN8pP5CvxMZwg+YhfrTVuY2MirIreUnmPg52LkDcfQZIGT618dR46zeOjkpesV+lj4DD+JWfRVudS9Yr9LH6t\/H7\/AIObdQu4GtfhX8NYbJjgjUfFlwZiBnlfsls6jOOjfaOD\/Ca+Rfjd\/wAFjfj98edHtdP13xhYwadaana6slpY6Tb20cs9tMs8CuQpaSNZY0fy2YqxUbt2K+Xbuf7JaSSd40LAeuBX9IH7If8AwS3+Dv7K3wotdFs\/Cfh3xZqlxAp1TxBq+mw3l3q8hUbmy4cRwkjKwoQijn5mLO3pZTWzrPpz\/wBo5Ixte2i12Vla+3Vnr5HiOIeJ6tRfWnThC17aLW9lZWvs73Z8p+EP+DjnR7vwnpc2sfDPVJNWktInvWstWjW1acoDIYg6lhHuztDEkDGSTRX6SaZ8OvD+i6bb2dnoOj2lnaRLDBBDYxRxwxqAFRVC4VQAAAOABRX36y\/N0rfW1\/4Aj9SjluepJPGr\/wAFr\/M\/Pn\/gtX4i8U\/tP\/tDfCH9lPwfqkOkSfEIvruuzTbvLa1hMrw7wCPMSMWd5OYuN8lvb4ZSM1yP\/BRX\/gmX8Pf2Hf8Agk14qi8HeH11nxFDfaXPrPie+hWbVJ1+2xKzK3\/LGEFlURQ4UKSW3EvIfvbx1+xl4H+IP7Vfgv4zX9rfL468CWVxp+n3MN0Uhlgljnj2TR8htgurgrjHMrZ3YUL6N4s8J6b488M6jousWNrqek6xbS2V9Z3MQlgu4JUKSRSKeGVlLKQeoJFFfIViJYipXs5zTjF78seVJWXTW7dt+4sRwzHFTxVbE2c6icYS35YcqSsns73btufIf\/BLr\/gmn8Lfg3+yZ4N1XUPC\/hHxl4s8VaVb65qOu3unw37M1zEsqw27yB9sEaMqLs2iQqZCNzmvrbw94A0PwlpU1jpejaTpthcA+bbWlnHBDLkYO5VAByOOR0ryX9if9iiH9h\/w9rnhvQ\/GvijxB4IursXWhaJrLRzf8IyGLtNFBMFDtG7Mp2vwpQty8kjv7oRkV6mW4OFDDwpqCi0rWWu3n1v9\/c9nKMDTw2Fp01TUHFWsrPbTfrfe71fXU\/JP9jz\/AII8eA\/jR8A\/2hvhr4is4LPxz4N+I17pPh7xIIgl5p9vFY20ljIyqRvtpVmZ5ISdrBsja6RyJ9nf8Eovj3qHxa\/ZYtPDPii3fT\/iH8I7lvA3iqxkkEkiXVkBGk27P7xZYhG\/mL8jSCUKSFzXr3gH9nPw78Nfjb4+8faX\/aMeufEoaadbjlumktXksYGt4ZI4z\/q3MJRXwcMIkOMgkweF\/wBmDwt4K\/aK8UfFHS49QsfE3jTTrXTtcWK6ZbPUha5EE8kP3TOkZ8tZOojyB1YngwGURwkoSoJLeMvON24v1X5Nq+iPNyzIY4GdOeHio2vGXnG7cX5yWnybV9Eej0UUV759MFFFFABRRRQAUUUUAFFFFAH\/2Q==\"><\/p>"
}

где:

  • Content - изображение в кодировке base64, заключенный в HTML теги для изображений.

Приложить файл к требованию

curl -X POST -H "Devprom-Auth-Key:f14acb09aa3b63cd8608fdf4ccb6d355" -H "Content-Type:application/json" http://devprom.local/pm/clementine/api/latest/wikipagefile/items -d @wikipagefile.json

Содержимое wikipagefile.json:

{
   "ContentExt":"test.txt",
   "WikiPage":{
      "Id":Requirement.Id
   },
   "Content":"VGVzdA=="
}

где:

  • Requirement.Id - Id требования, к которому прикладывается файл;
  • Content - содержимое файла в кодировке base64.

Управление пожеланиями

Создание пожелания с определенным типом

curl -X POST -H "Devprom-Auth-Key:f14acb09aa3b63cd8608fdf4ccb6d355" -H "Content-Type:application/json" http://devprom.local/pm/clementine/api/latest/request/items -d @request.json

Содержимое request.json:

{
   "Caption":"Request",
   "Content":"Description",
   "Type":{
      "Id":RequestType.Id
   }
}

где:

  • RequestType.Id - Id типа пожелания.

Приложить файл к пожеланию

curl -X POST -H "Devprom-Auth-Key:f14acb09aa3b63cd8608fdf4ccb6d355" -H "Content-Type:application/json" http://devprom.local/pm/clementine/api/latest/attachment/items -d @attachment.json

Содержимое attachment.json:

{
   "FileExt":"test.txt",
   "ObjectId":Request.Id,
   "ObjectClass":"Request",
   "File":"VGVzdA=="
}

где:

  • Request.Id - Id пожелания, к которому прикладывается файл;
  • File - содержимое файла в кодировке base64.

Управление задачами

Создание задачи с исполнителем

curl -X POST -H "Devprom-Auth-Key:f14acb09aa3b63cd8608fdf4ccb6d355" -H "Content-Type:application/json" http://devprom.local/pm/clementine/api/latest/task/items -d @task.json

Содержимое task.json:

{
   "Assignee":{
      "Login":User.Login
   },
   "TaskType":{
      "ReferenceName":TaskType.ReferenceName
   },
   "Caption":"Task"
}

где:

  • User.Login - логин пользователя, который будет назначен исполнителем задачи;
  • TaskType.ReferenceName - кодовое имя типа задачи.

Создание задачи с трассировкой на пожелание

curl -X POST -H "Devprom-Auth-Key:f14acb09aa3b63cd8608fdf4ccb6d355" -H "Content-Type:application/json" http://devprom.local/pm/clementine/api/latest/task/items -d @task.json

Содержимое task.json:

{
   "TaskType":{
      "ReferenceName":TaskType.ReferenceName
   },
   "ChangeRequest":{
      "Id":Request.Id
   },
   "Caption":"Task"
}

где:

  • TaskType.ReferenceName - кодовое имя типа задачи;
  • Request.Id - Id связанного пожелания.

Списание времени по задаче

curl -X POST -H "Devprom-Auth-Key:f14acb09aa3b63cd8608fdf4ccb6d355" -H "Content-Type:application/json" http://devprom.local/pm/clementine/api/latest/activity/items -d @activity.json

Содержимое activity.json:

{
   "Task":{
      "Id":Task.Id
   },
   "Participant":{
      "Login":User.Login
   },
   "Capacity":5.0
}

где:

  • Task.Id - Id задачи у которой списывается время;
  • User.Login - логин пользователя, который списывает время.

Приложить файл к задаче

curl -X POST -H "Devprom-Auth-Key:f14acb09aa3b63cd8608fdf4ccb6d355" -H "Content-Type:application/json" http://devprom.local/pm/clementine/api/latest/attachment/items -d @attachment.json

Содержимое attachment.json:

{
   "FileExt":"test.txt",
   "ObjectId":Task.Id,
   "ObjectClass":"Task",
   "File":"VGVzdA=="
}

где:

  • Task.Id - Id задачи, к которой прикладывается файл;
  • File - содержимое файла в кодировке base64.

Управление тестированием

Создание тест-плана

curl -X POST -H "Devprom-Auth-Key:f14acb09aa3b63cd8608fdf4ccb6d355" -H "Content-Type:application/json" http://devprom.local/pm/clementine/api/latest/testscenario/items -d @test-plan.json

Содержимое test-plan.json:

{
   "Caption":"Test-plan",
   "IsDocument":1
}

Создание раздела тест-плана

curl -X POST -H "Devprom-Auth-Key:f14acb09aa3b63cd8608fdf4ccb6d355" -H "Content-Type:application/json" http://devprom.local/pm/clementine/api/latest/testscenario/items -d @testscenario.json

Содержимое testscenario.json:

{
   "Caption":"Test scenario",
   "Content":"Scenario content",
   "ParentPage":{
      "Id":"Testscenario.Id"
   },
   "PageType":{
      "ReferenceName":"section"
   }
}

где:

  • Testscenario.Id - Id тест-плана.

Приложить файл к тест-плану/сценарию

curl -X POST -H "Devprom-Auth-Key:f14acb09aa3b63cd8608fdf4ccb6d355" -H "Content-Type:application/json" http://devprom.local/pm/clementine/api/latest/wikipagefile/items -d @wikipagefile.json

Содержимое wikipagefile.json:

{
   "ContentExt":"test.txt",
   "WikiPage":{
      "Id":Testscenario.Id
   },
   "Content":"VGVzdA=="
}

где:

  • Testscenario.Id - Id тест-плана/тестового сценария, к которому прикладывается файл;
  • Content - содержимое файла в кодировке base64.

Создание тестового отчета

curl -X POST -H "Devprom-Auth-Key:f14acb09aa3b63cd8608fdf4ccb6d355" -H "Content-Type:application/json" http://devprom.local/pm/clementine/api/latest/testexecution/items -d @testexecution.json

Содержимое testexecution.json:

{
   "TestScenario":{
      "Id":Testscenario.Id
   },
   "Caption":"Test execution"
}

где:

  • Testscenario.Id - Id тест-плана/тестового сценария к которому создается тестовый отчет.

В результате создания тестового отчета для указанного Testscenario.Id и всех его дочерних страниц будет автоматически созданы сущности - позиция теста (TestCaseExecution)

Указать результат позиции теста

curl -X PUT -H "Devprom-Auth-Key:f14acb09aa3b63cd8608fdf4ccb6d355" -H "Content-Type:application/json" http://devprom.local/pm/clementine/api/latest/testcaseexecution/items/id -d @caseexecution.json

где:

  • id - Id обновляемой позиции теста.

Содержимое caseexecution.json:

{
   "Result":{
      "ReferenceName":TestExecutionResult.ReferenceName
   }
}

где:

  • TestExecutionResult.ReferenceName - кодовое имя результата тестирования (доступные значения по умолчанию: "succeeded", "failed", "blocked").

JavaScript

Если вы хотите отправлять заявки пользователей при помощи собственной Web-формы, то вам пригодится следующий пример, который отправляет тестовую заявку в проект поддержки. Перед использованием этого примера вам необходимо:

  1. Создать проект поддержки (или использовать любой существующий проект), из адресной строки браузера скопировать путь к разделам проекта, например, https://demo.myalm.ru/pm/support
  2. Получить ключ для использования API, позволяющий только сохранять заявки, но не разрешающий читать остальные заявки. Для этого нужно перейти по ссылке аналогичной для вашего проекта, например, https://demo.myalm.ru/pm/support/api/key-writeonly Полученный ключ необходимо подставить в заголовок Devprom-Auth-Key.
 <!DOCTYPE html>
 <html lang="en">
 <head>
     <script src="https://code.jquery.com/jquery-1.11.3.min.js" type="text/javascript"></script>
 </head>
 <body>
 <script type="text/javascript">
     $(document).ready(function() {
         $.ajax({
             dataType: 'json',
             type: 'POST',
             url: 'https://demo.myalm.ru/pm/support/api/latest/issues',
             data: JSON.stringify({
                 'Caption':'Test',
                 'Author': 'somebody@mail.ru'
             }),
             headers: {
                 'Devprom-Auth-Key': 'a806f6e2af139ea856db981c20278865',
             },
             success: function(data) {
                 $('body').append('div').html('Issue id = ' + data.Id);
             }
         });
     });
 </script>
 </body>
 </html>


PHP

<?php
 $appUrl = 'https://demo.myalm.ru';
 $projectCode = 'kanban';
 $authKey = '974ccef5dd367cc448b8c1d1a9bdb2fd';
 
 $curl = curl_init();
 curl_setopt($curl, CURLOPT_FOLLOWLOCATION, true);
 curl_setopt($curl, CURLOPT_HEADER, false);
 curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
 curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
 curl_setopt($curl, CURLOPT_TIMEOUT, 60);
 curl_setopt($curl, CURLOPT_HTTPHEADER,
 	array(
 		"Content-Type: application/json",
 		"Devprom-Auth-Key: ".$authKey
 	)
 );
 
 // get all issues
 curl_setopt($curl, CURLOPT_URL, $appUrl.'/pm/'.$projectCode.'/api/latest/issues');
 curl_setopt($curl, CURLOPT_HTTPGET, true);
 $result = curl_exec($curl);
 var_export(json_decode($result, true));
 
 // create a new issue
 curl_setopt($curl, CURLOPT_URL, $appUrl.'/pm/'.$projectCode.'/api/latest/issues');
 curl_setopt($curl, CURLOPT_POST, true);
 curl_setopt($curl, CURLOPT_HTTPGET, false);
 curl_setopt($curl, CURLOPT_POSTFIELDS, 
 	json_encode(
 		array(
 			'Caption' => 'Issue title',
 			'Description' => 'Issue description'
 		)
 	)
 );
 $result = curl_exec($curl);
 var_export(json_decode($result, true));
 
 curl_close($curl);


C

using System;
 using System.Collections.Generic;
 using System.Linq;
 using System.Text;
 using System.Net;
 using System.IO;
 using System.Web.Script.Serialization;
 
 class DevpromRestService
 {
 	public void updateIssue()
 	{
 		// Получим список пожеланий в проекте
 		List<Issue> wasIssues = new JavaScriptSerializer().Deserialize<List<Issue>>(
 				makeRequest("GET", "issues")
 		);
 		
 		// Создаем новое пожелание
 		Issue newIssue = new JavaScriptSerializer().Deserialize<Issue>(
 				makeRequest("POST", "issues", new JavaScriptSerializer().Serialize(
 						new Issue
 						{
 							Caption = "Название нового пожелания",
 							Description = "Описание нового пожелания",
 							Priority = "2"
 						}
 				))
 		);
 
 		// Редактируем ранее созданное пожелание
 		makeRequest("PUT", "issues/" + newIssue.Id, new JavaScriptSerializer().Serialize(
 				new Issue
 				{
 					Description = "Изменненное название пожелания",
 					Priority = "1"
 				}
 		));
 
 		// Удалим созданное пожелание
 		makeRequest("DELETE", "issues/" + newIssue.Id);
 	}
 
 	public string makeRequest(string method, string route, string data = "")
 	{
 		HttpWebRequest request = (HttpWebRequest) WebRequest.Create(
 				TestHelper.appHostUrl + "/pm/<project-code>/api/v1/" + route
 		);
 
 		request.Method = method;
 
 		request.ContentLength = 0;
 		request.ContentType = "application/json";
 
 		request.Headers.Add(
 				"Authorization", 
 				"Basic " + Convert.ToBase64String(
 								Encoding.ASCII.GetBytes(
 										<логин-пользователя> + ":" + <пароль-пользователя>
 								)
 						   )
 		);
 
 		var bytes = Encoding.GetEncoding("windows-1251").GetBytes(data);
 
 		request.ContentLength = bytes.Length;
 
 		if (!String.IsNullOrEmpty(data))
 		{
 			using (var writeStream = request.GetRequestStream())
 			{
 				writeStream.Write(bytes, 0, bytes.Length);
 			}
 		}
 
 		HttpWebResponse response = (HttpWebResponse) request.GetResponse();
 		
 		if (response.StatusCode != HttpStatusCode.OK)
 		{
 			throw new ApplicationException(
 					String.Format("Request failed. Received HTTP {0}", response.StatusCode)
 			);
 		}
 
 		return (new StreamReader(response.GetResponseStream(), Encoding.UTF8)).ReadToEnd();
 	}
 }


Создание проекта

Для создания проекта программным путем необходимо отправить POST запрос:

curl -H "Content-Type: application/x-www-form-urlencoded" -X POST -d "Caption=Test1&CodeName=test1&Template=44&DemoData=N" http://<адрес_сервера>/projects/new?appkey=<ключ>
Название параметра Назначение параметра
Caption Название проекта
CodeName Кодовое имя проекта, используемое в адресной строке ссылок на проектные артефакты
Template Идентификатор процесса, который должен быть использован для создания проекта
DemoData N - не использовать демонстрационные данные
appkey Ключ для аутентификации, который можно получить на странице профиля участника (Ключи - Авторизация по URL), от имени которого будет создаваться проект. Данный пользователь автоматически становится координатором (руководителем) проекта.