Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 5.3

Resource: Project Categories ( /api/projectcategories )

Project Categories (collection) resource

Root Relation: ProjectCategories

This resource supports the following methods: GET, POST

Methods

GET


Retrieves a list of all project categories.

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

Supported Expansions

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).

StatusDescription
200 - OKReturned if the request was completed successfully.

Example - Get all project categories

Retrieves a list of all project categories.

Request Headers

KeyValueDescription
Acceptapplication/json

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

Code Block
languagenone
{
  "Items": [
    {
      "Id": "dc8b3352-05cf-4b54-868b-a1f6c3cc73ba",
      "Name": "Active",
      "OrderNumber": 0,
      "OrganisationId": "d7b68899-6cdc-4ec3-8f83-b19a4d9d27d3",
      "OrganisationName": "Acme Inc",
      "ParentId": null,
      "ParentName": null,
      "HasChildren": true,
      "HasProjects": false,
      "HasParent": false,
      "Expands": [
        "Projects",
        "Parent",
        "Organisation",
        "Children"
      ],
      "Self": "http://localhost/api/projectcategory/dc8b3352-05cf-4b54-868b-a1f6c3cc73ba"
    },
    {
      "Id": "092c1c83-cfe7-4075-aea8-4dc445f8d87d",
      "Name": "Mobile",
      "OrderNumber": 0,
      "OrganisationId": null,
      "OrganisationName": null,
      "ParentId": "dc8b3352-05cf-4b54-868b-a1f6c3cc73ba",
      "ParentName": "Active",
      "HasChildren": false,
      "HasProjects": false,
      "HasParent": true,
      "Expands": [
        "Projects",
        "Parent",
        "Organisation",
        "Children"
      ],
      "Self": "http://localhost/api/projectcategory/092c1c83-cfe7-4075-aea8-4dc445f8d87d"
    },
    {
      "Id": "4b538f8f-994b-4a82-8874-22a16586eebf",
      "Name": "Archived",
      "OrderNumber": 1,
      "OrganisationId": "d7b68899-6cdc-4ec3-8f83-b19a4d9d27d3",
      "OrganisationName": "Acme Inc",
      "ParentId": null,
      "ParentName": null,
      "HasChildren": false,
      "HasProjects": false,
      "HasParent": false,
      "Expands": [
        "Projects",
        "Parent",
        "Organisation",
        "Children"
      ],
      "Self": "http://localhost/api/projectcategory/4b538f8f-994b-4a82-8874-22a16586eebf"
    }
  ]
}

Status Code

200 - OK

Example - Retrieves filtered set of project categories.

Retrieves a list of project categories filtered by name.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
$filterName eq 'Archive'Retrieves a list of all project categories with the name 'Archive'.

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Response Body

Code Block
languagenone
{
  "Items": [
    {
      "Id": "4b538f8f-994b-4a82-8874-22a16586eebf",
      "Name": "Archived",
      "OrderNumber": 1,
      "OrganisationId": "d7b68899-6cdc-4ec3-8f83-b19a4d9d27d3",
      "OrganisationName": "Acme Inc",
      "ParentId": null,
      "ParentName": null,
      "HasChildren": false,
      "HasProjects": false,
      "HasParent": false,
      "Expands": [
        "Projects",
        "Parent",
        "Organisation",
        "Children"
      ],
      "Self": "http://localhost/api/projectcategory/4b538f8f-994b-4a82-8874-22a16586eebf"
    }
  ]
}

Status Code

200 - OK

POST


Create a new project category.

Required Permissions

  • Administration/Organisation/ManageOrganisation

Supported Expansions

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).

StatusDescription
201 - CreatedReturned if the project category was created successfully.
403 - ForbiddenReturned if the project category could not be created (due to lack of permissions or an invalid json request).
409 - ConflictReturned if the project category name is already in use.

Example - Create a new project category (for organisation).

Create a new project category directly underneath an organisation (note: if OrganisationId and ParentId are both omitted, then default organisation will be used).

Request Headers

KeyValueDescription
Acceptapplication/json

Request Body

Code Block
languagenone
{
  "Name": "Sandbox",
  "OrderNumber": 3
}

Response Headers

KeyValueDescription
Locationhttp://localhost/api/projectcategory/4bb709c2-e0e7-4af3-9f60-a045016a9610
Content-Typeapplication/json; charset=utf-8

Response Body

Code Block
languagenone
{
  "Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "Name": "Sandbox",
  "OrderNumber": 3,
  "OrganisationId": "d7b68899-6cdc-4ec3-8f83-b19a4d9d27d3",
  "OrganisationName": "Acme Inc",
  "ParentId": null,
  "ParentName": null,
  "HasChildren": false,
  "HasProjects": false,
  "HasParent": false,
  "Self": "http://localhost/api/projectcategory/4bb709c2-e0e7-4af3-9f60-a045016a9610"
}

Status Code

201 - Created

Example - Create a new project category (for parent).

Create a new project category underneath another project category.

Request Headers

KeyValueDescription
Acceptapplication/json

Request Body

Code Block
languagenone
{
  "Name": "Desktop",
  "ParentId": "dc8b3352-05cf-4b54-868b-a1f6c3cc73ba"
}

Response Headers

KeyValueDescription
Locationhttp://localhost/api/projectcategory/4bb709c2-e0e7-4af3-9f60-a045016a9610
Content-Typeapplication/json; charset=utf-8

Response Body

Code Block
languagenone
{
  "Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
  "Name": "Desktop",
  "OrderNumber": 0,
  "OrganisationId": null,
  "OrganisationName": null,
  "ParentId": "dc8b3352-05cf-4b54-868b-a1f6c3cc73ba",
  "ParentName": "Active",
  "HasChildren": false,
  "HasProjects": false,
  "HasParent": true,
  "Self": "http://localhost/api/projectcategory/4bb709c2-e0e7-4af3-9f60-a045016a9610"
}

Status Code

201 - Created