Resource: Projects ( /api/projects )

Projects collection resource, allowing the search and retrieval of all visible projects.

Root Relation: Projects

This resource supports the following methods: GET, POST

Methods

GET

Retrieves all (or a subset) of projects that are visible to the user.

This method supports the OData parameters $filter, $top, $take, $orderby and $inlinecount. See OData Topic for more details.

Required Permissions

TestManagement/ManageExecutions/View
TestManagement/ManageScripts/View
TestManagement/ManageIncidents/View
TestManagement/ManageRequirements/View

Supported Expansions

TimeTrackingConfiguration
ProjectCategory
Statuses
Priorities
RequirementTypes
RequirementStatuses
RequirementDifficulties
IncidentTypes
TestTypes
IncidentResolutions
IncidentStatuses
Versions
Components
ExecutionPackages
ScriptPackages
RequirementPackages
ExternalSystemLinks
Widgets

For more details on expansions, please see the Expand help topic.

Status Codes

These are the expected status codes returned by the service. In addition, some other status codes may be returned if either an internal error occurs or there is an authentication issue (such as an expired OAuth token).

Status	Description
200 - OK	Returned if the request was completed successfully.

Example - Get All Projects

An example of Retrieving all projects.

Request Headers

Key	Value	Description
Accept	application/json

Response Headers

Key	Value	Description
Content-Type	application/json; charset=utf-8

Response Body

{
  "Items": [
    {
      "Id": "eb06e5d8-f774-4b0f-a95c-a911c13527a9",
      "Name": "Project ABC",
      "OrganisationId": "ce67194e-29e2-49ee-af97-bb17aacedce0",
      "OrganisationName": "Acme Inc.",
      "ProjectCategoryId": null,
      "ProjectCategoryName": null,
      "Description": null,
      "EstimatedEndDate": null,
      "ManagerId": null,
      "ManagerUserName": null,
      "Slug": "abc",
      "AutoNumberRequirements": false,
      "AutoNumberScripts": false,
      "Independent": false,
      "RequirementNumberReadOnly": false,
      "ScriptNumberReadOnly": false,
      "OrderNumber": 0,
      "StartDate": null,
      "Expands": [
        "Statuses",
        "Priorities",
        "RequirementTypes",
        "RequirementStatuses",
        "RequirementDifficulties",
        "IncidentTypes",
        "TestTypes",
        "IncidentResolutions",
        "IncidentStatuses",
        "Versions",
        "Components",
        "ExecutionPackages",
        "ScriptPackages",
        "RequirementPackages",
        "TimeTrackingConfiguration"
      ],
      "Self": "http://localhost/api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9",
      "Links": [
        {
          "Title": "Project Tickets Search",
          "Href": "http://localhost/api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9/tickets",
          "Rel": "Tickets"
        },
        {
          "Title": "Project Assignees Search",
          "Href": "http://localhost/api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9/assignees",
          "Rel": "Assignees"
        },
        {
          "Title": "Widgets (Editors for entity fields)",
          "Href": "http://localhost/api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9/widgets",
          "Rel": "Widgets"
        }
      ]
    },
    {
      "Id": "cd69b4f5-507d-4735-b0af-8493c91b43a8",
      "Name": "Project XYZ",
      "OrganisationId": "ce67194e-29e2-49ee-af97-bb17aacedce0",
      "OrganisationName": "Acme Inc.",
      "ProjectCategoryId": null,
      "ProjectCategoryName": null,
      "Description": null,
      "EstimatedEndDate": null,
      "ManagerId": null,
      "ManagerUserName": null,
      "Slug": "xyz",
      "AutoNumberRequirements": false,
      "AutoNumberScripts": false,
      "Independent": false,
      "RequirementNumberReadOnly": false,
      "ScriptNumberReadOnly": false,
      "OrderNumber": 0,
      "StartDate": null,
      "Expands": [
        "Statuses",
        "Priorities",
        "RequirementTypes",
        "RequirementStatuses",
        "RequirementDifficulties",
        "IncidentTypes",
        "TestTypes",
        "IncidentResolutions",
        "IncidentStatuses",
        "Versions",
        "Components",
        "ExecutionPackages",
        "ScriptPackages",
        "RequirementPackages",
        "TimeTrackingConfiguration"
      ],
      "Self": "http://localhost/api/project/cd69b4f5-507d-4735-b0af-8493c91b43a8",
      "Links": [
        {
          "Title": "Project Tickets Search",
          "Href": "http://localhost/api/project/cd69b4f5-507d-4735-b0af-8493c91b43a8/tickets",
          "Rel": "Tickets"
        },
        {
          "Title": "Project Assignees Search",
          "Href": "http://localhost/api/project/cd69b4f5-507d-4735-b0af-8493c91b43a8/assignees",
          "Rel": "Assignees"
        },
        {
          "Title": "Widgets (Editors for entity fields)",
          "Href": "http://localhost/api/project/cd69b4f5-507d-4735-b0af-8493c91b43a8/widgets",
          "Rel": "Widgets"
        }
      ]
    }
  ]
}

Status Code

200 - OK

Example - Get Projects filtered by name

An example of retrieving a set of projects by name, by using the ODATA $filter query parameter.

Request Headers

Key	Value	Description
Accept	application/json

Request Parameters

Key	Value	Description
$filter	Name eq 'Project ABC'	The ODATA $filter parameter, this query parameter should be url encoded i.e. $filter=Name%20eq%20'Project ABC'

Response Headers

Key	Value	Description
Content-Type	application/json; charset=utf-8

Response Body

{
  "Items": [
    {
      "Id": "eb06e5d8-f774-4b0f-a95c-a911c13527a9",
      "Name": "Project ABC",
      "OrganisationId": "ce67194e-29e2-49ee-af97-bb17aacedce0",
      "OrganisationName": "Acme Inc.",
      "ProjectCategoryId": null,
      "ProjectCategoryName": null,
      "Description": null,
      "EstimatedEndDate": null,
      "ManagerId": null,
      "ManagerUserName": null,
      "Slug": "abc",
      "AutoNumberRequirements": false,
      "AutoNumberScripts": false,
      "Independent": false,
      "RequirementNumberReadOnly": false,
      "ScriptNumberReadOnly": false,
      "OrderNumber": 0,
      "StartDate": null,
      "Expands": [
        "Statuses",
        "Priorities",
        "RequirementTypes",
        "RequirementStatuses",
        "RequirementDifficulties",
        "IncidentTypes",
        "TestTypes",
        "IncidentResolutions",
        "IncidentStatuses",
        "Versions",
        "Components",
        "ExecutionPackages",
        "ScriptPackages",
        "RequirementPackages",
        "TimeTrackingConfiguration"
      ],
      "Self": "http://localhost/api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9",
      "Links": [
        {
          "Title": "Project Tickets Search",
          "Href": "http://localhost/api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9/tickets",
          "Rel": "Tickets"
        },
        {
          "Title": "Project Assignees Search",
          "Href": "http://localhost/api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9/assignees",
          "Rel": "Assignees"
        },
        {
          "Title": "Widgets (Editors for entity fields)",
          "Href": "http://localhost/api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9/widgets",
          "Rel": "Widgets"
        }
      ]
    }
  ]
}

Status Code

200 - OK

POST

Create a new project.

Required Permissions

Project/ManageProjects

Supported Expansions

TimeTrackingConfiguration
ProjectCategory
Statuses
Priorities
RequirementTypes
RequirementStatuses
RequirementDifficulties
IncidentTypes
TestTypes
IncidentResolutions
IncidentStatuses
Versions
Components
ExecutionPackages
ScriptPackages
RequirementPackages
ExternalSystemLinks
Widgets

For more details on expansions, please see the Expand help topic.

Status Codes

These are the expected status codes returned by the service. In addition, some other status codes may be returned if either an internal error occurs or there is an authentication issue (such as an expired OAuth token).

Status	Description
201 - Created	Returned if the new project was created successfully.
403 - Forbidden	Returned if the user does not have permission to create a project.
409 - Conflict	Returned if the projects name is already in use.

Example - Create a project

Example of creating a new project.

Request Headers

Key	Value	Description
Accept	application/json
Content-type	application/json

Request Body

{
  "Name": "My New Project",
  "ProjectCategoryId": "28f16438-8dfa-49cc-8db3-18aa1803cb86",
  "Description": "My new ET project",
  "EstimatedEndDate": "2012-12-31T11:00:00Z",
  "ManagerId": "83116d87-fff5-408b-8cdd-5491d17a9a26",
  "AutoNumberRequirements": true,
  "AutoNumberScripts": true,
  "Independent": false,
  "RequirementNumberReadOnly": true,
  "ScriptNumberReadOnly": false,
  "OrderNumber": 1,
  "StartDate": "2011-12-31T11:00:00Z",
  "TimeTrackingConfiguration": {
    "HoursPerDay": 24,
    "DaysPerWeek": 7
  }
}

Response Headers

Key	Value	Description
Location	http://localhost/api/project/4bb709c2-e0e7-4af3-9f60-a045016a9610
Content-Type	application/json; charset=utf-8

Response Body

{
  "Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "Name": "My New Project",
  "OrganisationId": "ce67194e-29e2-49ee-af97-bb17aacedce0",
  "OrganisationName": "Acme Inc.",
  "ProjectCategoryId": "28f16438-8dfa-49cc-8db3-18aa1803cb86",
  "ProjectCategoryName": "Current Projects",
  "Description": "My new ET project",
  "EstimatedEndDate": "2012-12-31T11:00:00Z",
  "ManagerId": "83116d87-fff5-408b-8cdd-5491d17a9a26",
  "ManagerUserName": "joeb",
  "Slug": "my-new-project",
  "AutoNumberRequirements": true,
  "AutoNumberScripts": true,
  "Independent": false,
  "RequirementNumberReadOnly": false,
  "ScriptNumberReadOnly": false,
  "OrderNumber": 1,
  "StartDate": "2011-12-31T11:00:00Z",
  "Self": "http://localhost/api/project/4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "Links": [
    {
      "Title": "Project Tickets Search",
      "Href": "http://localhost/api/project/4bb709c2-e0e7-4af3-9f60-a045016a9610/tickets",
      "Rel": "Tickets"
    },
    {
      "Title": "Project Assignees Search",
      "Href": "http://localhost/api/project/4bb709c2-e0e7-4af3-9f60-a045016a9610/assignees",
      "Rel": "Assignees"
    },
    {
      "Title": "Widgets (Editors for entity fields)",
      "Href": "http://localhost/api/project/4bb709c2-e0e7-4af3-9f60-a045016a9610/widgets",
      "Rel": "Widgets"
    }
  ]
}

Status Code

201 - Created

Example - Create a project using template

An example of creating a new project using a template (using the Id for the template retrieved from the list of project templates at /api/projecttemplates) - we leave all other configuration to be their default values.

Request Headers

Key	Value	Description
Accept	application/json
Content-type	application/json

Request Body

{ 
    "Name": "My New Project",
    "TemplateId": "C3A156A4-5CE0-4773-938A-9C6EADC030FD"
}

Response Headers

Key	Value	Description
Location	http://localhost/api/project/4bb709c2-e0e7-4af3-9f60-a045016a9610
Content-Type	application/json; charset=utf-8

Response Body

{
  "Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "Name": "My New Project",
  "OrganisationId": "ce67194e-29e2-49ee-af97-bb17aacedce0",
  "OrganisationName": "Acme Inc.",
  "ProjectCategoryId": null,
  "ProjectCategoryName": null,
  "Description": null,
  "EstimatedEndDate": null,
  "ManagerId": null,
  "ManagerUserName": null,
  "Slug": "my-new-project",
  "AutoNumberRequirements": false,
  "AutoNumberScripts": false,
  "Independent": false,
  "RequirementNumberReadOnly": false,
  "ScriptNumberReadOnly": false,
  "OrderNumber": 0,
  "StartDate": null,
  "Self": "http://localhost/api/project/4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "Links": [
    {
      "Title": "Project Tickets Search",
      "Href": "http://localhost/api/project/4bb709c2-e0e7-4af3-9f60-a045016a9610/tickets",
      "Rel": "Tickets"
    },
    {
      "Title": "Project Assignees Search",
      "Href": "http://localhost/api/project/4bb709c2-e0e7-4af3-9f60-a045016a9610/assignees",
      "Rel": "Assignees"
    },
    {
      "Title": "Widgets (Editors for entity fields)",
      "Href": "http://localhost/api/project/4bb709c2-e0e7-4af3-9f60-a045016a9610/widgets",
      "Rel": "Widgets"
    }
  ]
}

Status Code

201 - Created