Resource: Projects ( /api/projects )
Projects collection resource, allowing the search and retrieval of all visible projects.
Root Relation: Projects
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/View
Supported Expansions
- ExternalSystemLinks
- TimeTrackingConfiguration
- ProjectCategory
- Statuses
- Priorities
- RequirementTypes
- RequirementStatuses
- RequirementDifficulties
- IncidentTypes
- TestTypes
- IncidentResolutions
- IncidentStatuses
- Versions
- Components
- ExecutionPackages
- ScriptPackages
- RequirementPackages
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"
}
]
},
{
"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"
}
]
}
]
}
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"
}
]
}
]
}
Status Code
200 - OK
POST
Create a new project.
Required Permissions
- Project/ManageProject
Supported Expansions
- ExternalSystemLinks
- TimeTrackingConfiguration
- ProjectCategory
- Statuses
- Priorities
- RequirementTypes
- RequirementStatuses
- RequirementDifficulties
- IncidentTypes
- TestTypes
- IncidentResolutions
- IncidentStatuses
- Versions
- Components
- ExecutionPackages
- ScriptPackages
- RequirementPackages
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"
}
]
}
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"
}
]
}
Status Code
201 - Created