API: Categories

The categories endpoints return collections or single entities of type Category. The following tables list the different properties of Category entities.

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

{
  "_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."
    }
  }
}

id
integer

required path

ID of the project whose categories will be listed

Example:
1

200

{
  "_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."
    }
  }
}