API: Budgets

Note: Budgets are currently only implemented as a stub. Further properties of budgets might be added at a future date, however they will require the view budget permission to be displayed.

Linked Properties:

Link Description Type Constraints Supported operations
self This budget Budget not null READ

Properties

Property Description Type Constraints Supported operations Condition
id Budget id Integer x > 0 READ
subject Budget name String not empty READ

Methods

View budget

id
integer

required path

Budget id

Example:
1

200

OK

{
  "_links": {
    "self": {
      "href": "/api/v3/budgets/1",
      "title": "Q3 2015"
    }
  },
  "_type": "Budget",
  "id": 1,
  "subject": "Q3 2015"
}
BudgetModel
{
  "type": "object",
  "properties": {
    "_links": {
      "type": "object",
      "required": [
        "self"
      ],
      "properties": {
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This budget\n\n**Resource**: Budget",
              "readOnly": true
            }
          ]
        }
      }
    }
  },
  "example": {
    "_type": "Budget",
    "_links": {
      "self": {
        "href": "/api/v3/budgets/1",
        "title": "Q3 2015"
      }
    },
    "id": 1,
    "subject": "Q3 2015"
  }
}

403

Returned if the client does not have sufficient permissions.

Required permission: view work packages or view budgets (on the budgets project)

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not allowed to see this budget."
}
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."
    }
  }
}

View budgets of a project

id
integer

required path

Project id

Example:
1

200

OK

{
  "_embedded": {
    "elements": [
      {
        "_links": {
          "self": {
            "href": "/api/v3/budgets/1",
            "title": "Q3 2015"
          }
        },
        "_type": "Budget",
        "id": 1,
        "subject": "Q3 2015"
      },
      {
        "_links": {
          "self": {
            "href": "/api/v3/budgets/2",
            "title": "Q4 2015"
          }
        },
        "_type": "Budget",
        "id": 2,
        "subject": "Q4 2015"
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/api/v3/projects/1/budgets"
    }
  },
  "_type": "Collection",
  "count": 2,
  "total": 2
}
Budgets_by_ProjectModel
{
  "type": "object",
  "example": {
    "_links": {
      "self": {
        "href": "/api/v3/projects/1/budgets"
      }
    },
    "_type": "Collection",
    "total": 2,
    "count": 2,
    "_embedded": {
      "elements": [
        {
          "_type": "Budget",
          "_links": {
            "self": {
              "href": "/api/v3/budgets/1",
              "title": "Q3 2015"
            }
          },
          "id": 1,
          "subject": "Q3 2015"
        },
        {
          "_type": "Budget",
          "_links": {
            "self": {
              "href": "/api/v3/budgets/2",
              "title": "Q4 2015"
            }
          },
          "id": 2,
          "subject": "Q4 2015"
        }
      ]
    }
  }
}

403

Returned if the client does not have sufficient permissions to see the budgets of the given project.

Required permission: view work packages or view budgets

Note that you will only receive this error, if you are at least allowed to see the corresponding project.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not allowed to see the budgets of this project."
}
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."
    }
  }
}

404

Returned if either:

  • the project does not exist

  • the client does not have sufficient permissions to see the project

  • the costs module is not enabled on the given project

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