# Group 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                 |                             |

## Budget [/api/v3/budgets/{id}]

+ Model
    + Body

            {
                "_type" : "Budget",
                "_links" : {
                    "self" : {
                        "href" : "/api/v3/budgets/1",
                        "title" : "Q3 2015"
                    }
                },
                "id" : 1,
                "subject" : "Q3 2015"
            }


## view Budget [GET]

+ Parameters
    + id (required, integer, `1`) ... Budget id

+ Response 200 (application/hal+json)

    [Budget][]

+ Response 403 (application/hal+json)

    Returned if the client does not have sufficient permissions.

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

    + Body

            {
                "_type": "Error",
                "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
                "message": "You are not allowed to see this budget."
            }

## Budgets by Project [/api/v3/projects/{id}/budgets]

+ Model
    + Body

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


## view Budgets of a Project [GET]

+ Parameters
    + id (required, integer, `1`) ... Project id

+ Response 200 (application/hal+json)

    [Budgets by Project][]

+ Response 403 (application/hal+json)

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

    + Body

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

+ Response 404 (application/hal+json)

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

    + Body

            {
                "_type": "Error",
                "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
                "message": "The specified project does not exist."
            }