mirror of
https://github.com/opf/openproject.git
synced 2026-06-14 03:30:14 +00:00
ulferts
6826f90ee2
* rename costs, introduce budgets * move files from costs to budgets * rename cost_object to budget * remove unused code * move hook - should be turned into standard code in the long run * move type attributes change over to budgets * move patch to work_package proper * move budget menu item up * combine reporting, time and cost module * remove rails based time_entries & reports code * rename cost object filter * adapt menu spec expectations * use cost project module name in administration * include timeline labels in migration * properly place budget linking method * fix permitted params * remove outdated routing spec * adapt budget request specs * ensure order of descendent updates * remove outdated specs * fix checking for reporting to be enabled * fix displaying spent units * fix time entries activity event url * reenable current rate tab * fix path on budget page * allow bulk editing of budgets only in one project scenario * fix sanitizing reference in controller * include module required for format_date * fix reference to correct units from work package spent units * linting * remove outdated spec * remove outdated views and permission references * remove acts_as_event from time_entries There is no atom link for time entries * remove acts_as_event from projects There are no atom links for projects * introduce budget filter for cost reports * remove actions added to removed controller * move time entries to the costs module * factor in view_own permission when calculating time entry visibility * linting * move mounting of time entries * include budgets into api v3 documentation
337 lines
13 KiB
Plaintext
337 lines
13 KiB
Plaintext
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 Cost Entries
|
|
|
|
## Linked Properties:
|
|
| Link | Description | Type | Constraints | Supported operations |
|
|
|:-----------:|-------------------------------------------- | ------------- | --------------------- | -------------------- |
|
|
| self | This cost entry | CostEntry | not null | READ |
|
|
| project | The project in which this entry was logged | Project | not null | READ |
|
|
| costType | The type of this entry | CostType | not null | READ |
|
|
| user | The user logging this entry | User | not null | READ |
|
|
| workPackage | The work package that got the entry logged | WorkPackage | not null | READ |
|
|
|
|
## Properties
|
|
| Property | Description | Type | Constraints | Supported operations | Condition |
|
|
| :---------: | ------------------------------------------- | ----------- | ----------- | -------------------- | --------------------------- |
|
|
| id | cost entry id | Integer | x > 0 | READ | |
|
|
| spentUnits | The amount of units logged in this entry | Float | | READ | |
|
|
| spentOn | The date when the units were spent | Date | | READ | |
|
|
| createdAt | Time of creation | DateTime | | READ | |
|
|
| updatedAt | Time of the most recent change to the entry | DateTime | | READ | |
|
|
|
|
## Cost Entry [/api/v3/cost_entries/{id}]
|
|
|
|
+ Model
|
|
+ Body
|
|
|
|
{
|
|
"_type": "CostEntry",
|
|
"_links": {
|
|
"self": {
|
|
"href": "/api/v3/cost_entries/1"
|
|
},
|
|
"project": {
|
|
"href": "/api/v3/projects/1"
|
|
},
|
|
"costType": {
|
|
"href": "/api/v3/cost_types/1"
|
|
},
|
|
"user": {
|
|
"href": "/api/v3/users/1"
|
|
},
|
|
"workPackage": {
|
|
"href": "/api/v3/work_packages/1"
|
|
}
|
|
},
|
|
"id": 1,
|
|
"spentUnits": 3.14,
|
|
"spentOn": "2015-03-31",
|
|
"createdAt": "2015-03-31T08:51:20Z",
|
|
"updatedAt": "2015-03-31T08:51:20Z"
|
|
}
|
|
|
|
|
|
## view Cost Entry [GET]
|
|
|
|
+ Parameters
|
|
+ id (required, integer, `1`) ... Cost Entry id
|
|
|
|
+ Response 200 (application/hal+json)
|
|
|
|
[Cost Entry][]
|
|
|
|
+ Response 403 (application/hal+json)
|
|
|
|
Returned if the client does not have sufficient permissions.
|
|
|
|
**Required permission:** view cost entries **or** view own cost entries (on cost entry's project)
|
|
|
|
+ Body
|
|
|
|
{
|
|
"_type": "Error",
|
|
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
|
|
"message": "You are not allowed to see this cost entry."
|
|
}
|
|
|
|
## Cost Entries by work package [/api/v3/work_packages/{id}/cost_entries]
|
|
|
|
+ Model
|
|
+ Body
|
|
|
|
{
|
|
"_links":
|
|
{
|
|
"self":
|
|
{
|
|
"href": "/api/v3/work_packages/1/cost_entries"
|
|
}
|
|
},
|
|
"total": 1,
|
|
"count": 1,
|
|
"_type": "Collection",
|
|
"_embedded":
|
|
{
|
|
"elements": [
|
|
{
|
|
"_type": "CostEntry",
|
|
"_links": {
|
|
"self": {
|
|
"href": "/api/v3/cost_entries/1"
|
|
},
|
|
"project": {
|
|
"href": "/api/v3/projects/1"
|
|
},
|
|
"costType": {
|
|
"href": "/api/v3/cost_types/1"
|
|
},
|
|
"user": {
|
|
"href": "/api/v3/users/1"
|
|
},
|
|
"workPackage": {
|
|
"href": "/api/v3/work_packages/1"
|
|
}
|
|
},
|
|
"id": 1,
|
|
"spentUnits": 3.14,
|
|
"spentOn": "2015-03-31",
|
|
"createdAt": "2015-03-31T08:51:20Z",
|
|
"updatedAt": "2015-03-31T08:51:20Z"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
|
|
## list Cost Entries of a work package [GET]
|
|
|
|
+ Parameters
|
|
+ id (required, integer, `1`) ... work package id
|
|
|
|
+ Response 200 (application/hal+json)
|
|
|
|
[Cost Entries by work package][]
|
|
|
|
+ Response 403 (application/hal+json)
|
|
|
|
Returned if the client does not have sufficient permissions.
|
|
|
|
**Required permission:** view cost entries **or** view own cost entries (on work package's project)
|
|
|
|
*Note that you will only receive this error, if you are at least allowed to see the corresponding work package.*
|
|
|
|
+ Body
|
|
|
|
{
|
|
"_type": "Error",
|
|
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
|
|
"message": "You are not allowed to see the cost entries of this work package."
|
|
}
|
|
|
|
+ Response 404 (application/hal+json)
|
|
|
|
Returned if the work package does not exist or the client does not have sufficient permissions
|
|
to see it.
|
|
|
|
**Required permission:** view work package
|
|
|
|
*Note: A client without sufficient permissions shall not be able to test for the existence of a work package.
|
|
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 work package does not exist."
|
|
}
|
|
|
|
## Work package costs per type [/api/v3/work_packages/{id}/summarized_costs_by_type]
|
|
|
|
Returns a list of `AggregatedCostEntry`, with one entry per spent cost type.
|
|
The spent units of all cost entries visible to the current user are summed up for each entry.
|
|
|
|
An `AggregatedCostEntry` is a stripped down variant of a normal `CostEntry` which only has the link to
|
|
a `CostType` and the amount of `spentUnits`.
|
|
|
|
*Note that this is a preliminary endpoint. It is subject to future changes or removal.*
|
|
|
|
+ Model
|
|
+ Body
|
|
|
|
{
|
|
"_links":
|
|
{
|
|
"self":
|
|
{
|
|
"href": "/api/v3/work_packages/1/summarized_costs_by_type"
|
|
}
|
|
},
|
|
"total": 1,
|
|
"count": 1,
|
|
"_type": "Collection",
|
|
"_embedded":
|
|
{
|
|
"elements": [
|
|
{
|
|
"_type": "AggregatedCostEntry",
|
|
"_links": {
|
|
"costType": {
|
|
"href": "/api/v3/cost_types/1"
|
|
}
|
|
},
|
|
"spentUnits": 31.4
|
|
}
|
|
]
|
|
}
|
|
}
|
|
|
|
## Show aggregated costs of a work package [GET]
|
|
|
|
+ Parameters
|
|
+ id (required, integer, `1`) ... work package id
|
|
|
|
+ Response 200 (application/hal+json)
|
|
|
|
[Work package costs per type][]
|
|
|
|
+ Response 403 (application/hal+json)
|
|
|
|
Returned if the client does not have sufficient permissions.
|
|
|
|
**Required permission:** view cost entries **or** view own cost entries (on work package's project)
|
|
|
|
*Note that you will only receive this error, if you are at least allowed to see the corresponding work package.*
|
|
|
|
+ Body
|
|
|
|
{
|
|
"_type": "Error",
|
|
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
|
|
"message": "You are not allowed to see the cost entries of this work package."
|
|
}
|
|
|
|
+ Response 404 (application/hal+json)
|
|
|
|
Returned if the work package does not exist or the client does not have sufficient permissions
|
|
to see it.
|
|
|
|
**Required permission:** view work package
|
|
|
|
*Note: A client without sufficient permissions shall not be able to test for the existence of a work package.
|
|
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 work package does not exist."
|
|
}
|
|
|
|
# Group Cost Types
|
|
|
|
## Linked Properties:
|
|
| Link | Description | Type | Constraints | Supported operations |
|
|
|:---------:|-------------------------------------------- | ------------- | --------------------- | -------------------- |
|
|
| self | This cost type | CostType | not null | READ |
|
|
|
|
## Properties
|
|
| Property | Description | Type | Constraints | Supported operations | Condition |
|
|
| :---------: | ------------------------------------------- | ----------- | ----------- | -------------------- | --------------------------- |
|
|
| id | cost type id | Integer | x > 0 | READ | |
|
|
| name | cost type name | String | not empty | READ | |
|
|
| unit | The unit in which the costs are measured | String | not empty | READ | |
|
|
| unitPlural | The pluralized form of the unit | String | not empty | READ | |
|
|
| isDefault | `true` for the default type of new entries | Boolean | not null | READ | |
|
|
|
|
## Cost Type [/api/v3/cost_types/{id}]
|
|
|
|
+ Model
|
|
+ Body
|
|
|
|
{
|
|
"_type": "CostType",
|
|
"_links": {
|
|
"self": {
|
|
"href": "/api/v3/cost_types/1",
|
|
"title": "Energy cost"
|
|
}
|
|
},
|
|
"id": 1,
|
|
"name": "Energy cost",
|
|
"unit": "kWh",
|
|
"unitPlural": "kWh",
|
|
"isDefault": true
|
|
}
|
|
|
|
|
|
## view Cost Type [GET]
|
|
|
|
+ Parameters
|
|
+ id (required, integer, `1`) ... Cost Type id
|
|
|
|
+ Response 200 (application/hal+json)
|
|
|
|
[Cost Type][]
|
|
|
|
+ Response 403 (application/hal+json)
|
|
|
|
Returned if the client does not have sufficient permissions.
|
|
|
|
**Required permission:** view cost entries **or** view own cost entries (on any project)
|
|
|
|
+ Body
|
|
|
|
{
|
|
"_type": "Error",
|
|
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
|
|
"message": "You are not allowed to see cost types."
|
|
}
|
|
|
|
# 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 |
|
|
|:-----------:|-------------------------------------------- | --------------------------------- | --------------------- | -------------------- |
|
|
| costsByType | List of accumulated costs per cost type | Collection of AggregatedCostEntry | | READ / WRITE |
|
|
|
|
## Properties:
|
|
| Link | Description | Type | Constraints | Supported operations |
|
|
|:------------:|------------------------------------------------------------------- | ------------- | --------------------- | -------------------- |
|
|
| overallCosts | The total amount of user visible costs logged on this work package | String | | READ / WRITE |
|
|
|
|
`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.
|