API: Categories

Linked Properties

Link Description Type Constraints Supported operations
self This category Category not null READ
project The project of this category Project not null READ
defaultAssignee Default assignee for work packages of this category User READ

Local Properties

Property Description Type Constraints Supported operations
id Category id Integer x > 0 READ
name Category name String READ

Methods

View category

id
integer

required path

Category id

Example:
1

200

OK

{
  "_links": {
    "defaultAssignee": {
      "href": "/api/v3/users/42",
      "title": "John Sheppard"
    },
    "project": {
      "href": "/api/v3/projects/11",
      "title": "Example project"
    },
    "self": {
      "href": "/api/v3/categories/10",
      "title": "Category with assignee"
    }
  },
  "_type": "Category",
  "id": 10,
  "name": "Foo"
}
CategoryModel
{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "description": "Category id",
      "readOnly": true,
      "exclusiveMinimum": 0
    },
    "name": {
      "type": "string",
      "description": "Category name"
    },
    "_links": {
      "type": "object",
      "required": [
        "self",
        "project"
      ],
      "properties": {
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This category\n\n**Resource**: Category",
              "readOnly": true
            }
          ]
        },
        "project": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The project of this category\n\n**Resource**: Project",
              "readOnly": true
            }
          ]
        },
        "defaultAssignee": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Default assignee for work packages of this category\n\n**Resource**: User",
              "readOnly": true
            }
          ]
        }
      }
    }
  },
  "example": {
    "_links": {
      "self": {
        "href": "/api/v3/categories/10",
        "title": "Category with assignee"
      },
      "project": {
        "href": "/api/v3/projects/11",
        "title": "Example project"
      },
      "defaultAssignee": {
        "href": "/api/v3/users/42",
        "title": "John Sheppard"
      }
    },
    "_type": "Category",
    "id": 10,
    "name": "Foo"
  }
}

404

Returned if the category does not exist or the client does not have sufficient permissions to see it.

Required permission: view project (defining the category)

Note: A client without sufficient permissions shall not be able to test for the existence of a category. That’s why a 404 is returned here, even if a 403 might be more appropriate.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified category does not exist."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

List categories of a project

id
integer

required path

ID of the project whose categories will be listed

Example:
1

200

OK

{
  "_embedded": {
    "elements": [
      {
        "_links": {
          "defaultAssignee": {
            "href": "/api/v3/users/42",
            "title": "John Sheppard"
          },
          "project": {
            "href": "/api/v3/projects/11",
            "title": "Example project"
          },
          "self": {
            "href": "/api/v3/categories/10",
            "title": "Category with assignee"
          }
        },
        "_type": "Category",
        "id": 10,
        "name": "Foo"
      },
      {
        "_links": {
          "project": {
            "href": "/api/v3/projects/11"
          },
          "self": {
            "href": "/api/v3/categories/11"
          }
        },
        "_type": "Category",
        "id": 11,
        "name": "Bar"
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/api/v3/projects/11/categories"
    }
  },
  "_type": "Collection",
  "count": 2,
  "total": 2
}
Categories_by_ProjectModel
{
  "allOf": [
    {
      "$ref": "#/components/schemas/CollectionModel"
    },
    {
      "type": "object",
      "required": [
        "_links",
        "_embedded"
      ],
      "properties": {
        "_links": {
          "type": "object",
          "required": [
            "self"
          ],
          "properties": {
            "self": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Link"
                },
                {
                  "description": "The categories collection\n\n**Resource**: CategoriesCollection",
                  "readOnly": true
                }
              ]
            }
          }
        },
        "_embedded": {
          "type": "object",
          "properties": {
            "elements": {
              "type": "array",
              "readOnly": true,
              "items": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/CategoryModel"
                  },
                  {
                    "description": "Collection of Categories"
                  }
                ]
              }
            }
          }
        }
      }
    }
  ]
}

404

Returned if the project does not exist or the client does not have sufficient permissions to see it.

Required permission: view project

Note: A client without sufficient permissions shall not be able to test for the existence of a project. That’s why a 404 is returned here, even if a 403 might be more appropriate.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified project does not exist."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}