Create, Update and Delete operations

Introduction

This document describes the essence of Create, Update and Delete operations for TargetProcess REST API

Create a resource

To create a resource, the resource representation (either xml or json) should be POSTed to the collection URL. For example, to create a Project, the following request could be used:

POST http://localhost/TargetProcess/api/v1/Projects HTTP/1.1
Content-Type: application/xml
Host: localhost
Content-Length: 30
 
<Project Name="Some Project"/>

HTTP/1.1 201 Created
Content-Length: 505
Content-Type: application/xml; charset=utf-8
 
<Project Id="378" Name="Some Project">
  <Description nil="true" />
  <StartDate nil="true" />
  <EndDate nil="true" />
  <CreateDate>2011-09-01T18:33:17</CreateDate>
  <ModifyDate>2011-09-01T18:33:17</ModifyDate>
  <LastCommentDate nil="true" />
  <Tags></Tags>
  <IsActive>true</IsActive>
  <IsProduct>false</IsProduct>
  <Owner Id="316" />
  <Project nil="true" />
  <Program nil="true" />
  <Process Id="1" Name="All Practices" />
  <Company nil="true" />
  <CustomFields />
</Project>

The request should have the following headers:

• Content-Type
• Content-Length

There should be no defined Id field in the newly created resource.

If a resource was updated successfully, the response will include resource represenation and has HTTP status 200. Otherwise the response will include a description of the error.

You can control the results representaion using resultFormat, resultInclude, resultExclude and resultAppend URL parameters.

POST http://localhost/TargetProcess/api/v1/UserStories?resultFormat=json&resultInclude=[Id,Name,Project] HTTP/1.1
Content-Type: application/json
Host: localhost
Content-Length: 31
 
{Name:"CRUD", Project:{Id:378}}

HTTP/1.1 201 Created
Content-Length: 102
Content-Type: application/json; charset=utf-8
 
{
  "Id": 379,
  "Name": "CRUD",
  "Project": {
    "Id": 378,
    "Name": "Some Project"
  }
}

Update a resource

To update a resource, the resource with the corresponding ID and updated fields should be POSTed to the collection URL.

If a resource was updated successfully, the response will include resource represenation and has HTTP status 200.

You can control the results representaion using resultFormat, resultInclude, resultExclude and resultAppend URL parameters.

POST http://localhost/TargetProcess/api/v1/UserStories?resultFormat=json&resultInclude=[Id,Name,Project] HTTP/1.1
Content-Type: application/json
Host: localhost
Content-Length: 31
 
{Id:379, Name:"CRUD operations"}

HTTP/1.1 200 OK
Content-Length: 113
Content-Type: application/json; charset=utf-8
 
{
  "Id": 379,
  "Name": "CRUD operations",
  "Project": {
    "Id": 378,
    "Name": "Some Project"
  }
}

Update Custom Fields

POST http://localhost/TargetProcess/api/v1/Projects?resultFormat=json&resultInclude=[Id,CustomFields] HTTP/1.1
Content-Type: application/json
Host: localhost
Content-Length: 131
   
{
 "Id": 2794, 
 "CustomFields": [
  {
   "Name": "MyTextFieldName",
   "Value": "MyTextFieldValue"
  }, 
  {
   "Name": "MyNumberFieldName", 
   "Value": 1
  }
 ]
}

HTTP/1.1 200 OK
Content-Length: 270
Content-Type: application/json; charset=utf-8
   
{
  "Id": 2794,
  "Name": "MyProject",
  "CustomFields": [
    {
      "Name": "MyTextFieldName",
      "Type": "Text",
      "Value": "MyTextFieldValue"
    },
    {
      "Name": "MyNumberFieldName",
      "Type": "Number",
      "Value": 1
    }
  ]
}

Delete a resource

To delete a resource, the DELETE request should be sent to the resource Id.

If a resource was deleted, you will receive an empty response with HTTP status 200. If the requested resource is not found, response with HTTP Status 404 will be returned

Example

DELETE http://localhost/TargetProcess/api/v1/UserStories/376 HTTP/1.1
Host: localhost

HTTP/1.1 200 OK

Resource reference

Every resource has required fields to be set as a resource is created. Also, not all resources could be created or modified. Here is a reference table with resources and their required fields.

Resource	GET	CREATE	UPDATE	DELETE	Required Fields for CREATE
Processes				YES (can't delete default process)	Name
EntityTypes		NO	NO	NO
Priorities					Name, EntityType
Severities					Name
EntityStates				YES (can't delete Initial or Final states)	Name, EntityType
Generals		NO	NO	NO
Assignables		NO	NO	NO
GeneralUsers		NO	NO	NO
Users				YES (can't delete himself)	Email, Login, Password, FirstName, LastName
Projects					Name
Programs					Name
Releases					Name, Project
Iterations					Name, StartDate, EndDate, Project, Release
Features					Name, Project
UserStories					Name, Project
Tasks					Name, Project
Bugs					Name, Project
TestCases					Name, Steps, Success, Project
TestCaseRuns					TestPlanRun
TestPlans					Name, Project
TestPlanRuns					Name, Project, TestPlan
Times					Project, Description
Revisions					SourceControlID, Project
RevisionFiles					Revision
CustomActivities					Name, Project
Requests					Name, Project, EntityState
RequestTypes		NO	NO	NO
Builds					Name, Project
Comments					Description, General
Assignments					Assignable, GeneralUser, Role
Roles				YES (can't delete Role if it has EntityStates)	Name
Impediments					Name, Project
Companies					Companies
RoleEfforts					RoleEfforts
ProjectMembers					Project, User, Role
Attachments		NO	NO	NO

REST API Chapters

1. Getting Started
2. Concepts
1. Resources and collections
2. Context
3. Authentication
4. Response: Formats, Paging, Filters, Partial Get
5. Create, update and delete operations
6. Restful Storage
3. FAQ
4. Reference

Create, Update and Delete operations

1. Create a resource
2. Update a resource
3. Delete a resource
4. Resource reference