openproject/doc/apiv3.apib

FORMAT: 1A

# Additions to OpenProject API v3

This documentation lists the changes and additions that the costs plugin will
introduce to the core OpenProject API.

Unless otherwise stated it will only add endpoints and properties, but not remove anything that is
already present in the core API.

# Group Budgets

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

`spentTime` has its visibility condition changed! It is now only visible when the client is either allowed to view time entries, or if
he is allowed to see his own time entries in projects where the costs module is enabled.

*Note: Further properties of budgets might be added at a future date, however they will require the view budget permission to be displayed.*

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

# Group Work Packages

The following properties are only added to work packages in projects where the costs module is activated.
If the costs module is not available on a given work package, there will be no additional properties.

## Linked Properties:
|  Link      | Description                                 | Type          | Constraints           | Supported operations |
|:----------:|-------------------------------------------- | ------------- | --------------------- | -------------------- |
| costObject | The budget associated to this work package  | Budget        |                       | READ / WRITE         |