TheDude
/
openproject
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
OpenProject is the leading open source project management software.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
51343 Commits
139 Branches
203 Tags
1.2 GiB
Tag: Branch: Tree: a9b8e33c3d
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'a9b8e33c3d'
${ noResults }
openproject/docs/api/apiv3/endpoints/versions.apib

264 lines
12 KiB
Raw Normal View History Unescape

Extract APIV3 documentation into single endpoints This does not differentiate further inside an endpoint and while useful (for e.g., work packages) we should discuss how the structure inside an endpoint should look like.
8 years ago
# Group Versions
adding filter instance schemas
8 years ago
Work Packages can be assigned to a version. As such, versions serve to group Work Packages into logical units where each group comprises all the work packages that needs to be finished in order for the version to be finished.
Extract APIV3 documentation into single endpoints This does not differentiate further inside an endpoint and while useful (for e.g., work packages) we should discuss how the structure inside an endpoint should look like.
8 years ago
## Linked Properties
| Link | Description | Type | Constraints | Supported operations |
|:-------------------:|----------------------------------------- | ------------- | -------------------------------------------------------------- | -------------------- |
| self | This version | Version | not null | READ |
| definingProject | The project to which the version belongs | Project | only present if the project is visible for the current user | READ |
| availableInProjects | Projects where this version can be used | Projects | not null | READ |
## Local Properties
| Property | Description | Type | Constraints | Supported operations |
| :---------: | --------------------------------------------- | ----------- | ----------- | -------------------- |
| id | Version id | Integer | x > 0 | READ |
| name | Version name | String | not null | READ |
| description | | Formattable | not null | READ |
| startDate | | Date | | READ |
| endDate | | Date | | READ |
| status | The current status of the version | String | not null | READ |
| createdAt | Time of creation | DateTime | not null | READ |
| updatedAt | Time of the most recent change to the version | DateTime | not null | READ |
adding filter instance schemas
8 years ago
## Version [/api/v3/versions/{id}]
Extract APIV3 documentation into single endpoints This does not differentiate further inside an endpoint and while useful (for e.g., work packages) we should discuss how the structure inside an endpoint should look like.
8 years ago
+ Model
+ Body
{
"_links": {
adding filter instance schemas
8 years ago
"self": { "href": "/api/v3/versions/11" },
"definingProject": { "href": "/api/v3/projects/11" },
"availableInProjects": { "href": "/api/v3/versions/11/projects" }
},
"_type": "Version",
"id": 11,
"name": "v3.0 Alpha",
"description": {
"format": "plain",
"raw": "This version has a description",
"html": "This version has a description"
},
"startDate": "2014-11-20",
"endDate": null,
"status": "Open"
}
## View version [GET]
+ Parameters
+ id (required, integer, `1`) ... version id
+ Response 200 (application/hal+json)
[Version][]
+ Response 404 (application/hal+json)
Returned if the version does not exist or the client does not have sufficient permissions
to see it.
**Required permission:** view work packages **or** manage versions (any project where the version is available)
*Note: A client without sufficient permissions shall not be able to test for the existence of
a version. 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 version does not exist."
}
## Versions [/api/v3/versions{?filters}]
+ Model
+ Body
{
"_links": {
"self": { "href": "/api/v3/versions" }
Extract APIV3 documentation into single endpoints This does not differentiate further inside an endpoint and while useful (for e.g., work packages) we should discuss how the structure inside an endpoint should look like.
8 years ago
},
"total": 3,
"count": 3,
"_type": "Collection",
"_embedded":
{
"elements": [
{
"_links": {
"self": { "href": "/api/v3/versions/11" },
adding filter instance schemas
8 years ago
"definingProject": { "href": "/api/v3/projects/12" },
Extract APIV3 documentation into single endpoints This does not differentiate further inside an endpoint and while useful (for e.g., work packages) we should discuss how the structure inside an endpoint should look like.
8 years ago
"availableInProjects": { "href": "/api/v3/versions/11/projects" }
},
"_type": "Version",
"id": 11,
"name": "v3.0 Alpha",
"description": {
"format": "plain",
"raw": "This version has a description",
"html": "This version has a description"
},
"startDate": "2014-11-20",
"endDate": null,
"status": "Open"
},
{
"_links": {
"self": { "href": "/api/v3/versions/12" },
"definingProject": { "href": "/api/v3/projects/11" },
"availableInProjects": { "href": "/api/v3/versions/12/projects" }
},
"_type": "Version",
"id": 12,
"name": "v2.0",
"description": {
"format": "plain",
"raw": "",
"html": ""
},
"startDate": null,
"endDate": null,
"status": "Closed"
},
{
"_links": {
"self": { "href": "/api/v3/versions/10" },
adding filter instance schemas
8 years ago
"definingProject": { "href": "/api/v3/projects/13" },
"availableInProjects": { "href": "/api/v3/versions/13/projects" }
Extract APIV3 documentation into single endpoints This does not differentiate further inside an endpoint and while useful (for e.g., work packages) we should discuss how the structure inside an endpoint should look like.
8 years ago
},
"_type": "Version",
"id": 10,
"name": "v1.0",
"description": {
"format": "plain",
"raw": "",
"html": ""
},
"startDate": null,
"endDate": null,
"status": "Open"
}
]
}
}
adding filter instance schemas
8 years ago
## List versions [GET]
Extract APIV3 documentation into single endpoints This does not differentiate further inside an endpoint and while useful (for e.g., work packages) we should discuss how the structure inside an endpoint should look like.
8 years ago
adding filter instance schemas
8 years ago
Returns a collection of versions. The client can choose to filter the versions similar to how work packages are filtered. In addition to the provided filters, the server will reduce the result set to only contain versions, for which the requesting client has sufficient permissions (*view_work_packages*).
Extract APIV3 documentation into single endpoints This does not differentiate further inside an endpoint and while useful (for e.g., work packages) we should discuss how the structure inside an endpoint should look like.
8 years ago
+ Parameters
adding filter instance schemas
8 years ago
+ filters (optional, string, `[{ "sharing": { "operator": "*", "values": ["system"] }" }]`) ... JSON specifying filter conditions.
Accepts the same format as returned by the [queries](#queries) endpoint.
Currently supported filters are:
+ sharing: filters versions by how they are shared within the server (*none*, *descendants*, *hierarchy*, *tree*, *system*).
Extract APIV3 documentation into single endpoints This does not differentiate further inside an endpoint and while useful (for e.g., work packages) we should discuss how the structure inside an endpoint should look like.
8 years ago
+ Response 200 (application/hal+json)
adding filter instance schemas
8 years ago
[Versions][]
Extract APIV3 documentation into single endpoints This does not differentiate further inside an endpoint and while useful (for e.g., work packages) we should discuss how the structure inside an endpoint should look like.
8 years ago
adding filter instance schemas
8 years ago
## Versions by Project [/api/v3/projects/{project_id}/versions]
Extract APIV3 documentation into single endpoints This does not differentiate further inside an endpoint and while useful (for e.g., work packages) we should discuss how the structure inside an endpoint should look like.
8 years ago
+ Model
+ Body
{
"_links": {
adding filter instance schemas
8 years ago
"self": { "href": "/api/v3/projects/11/versions" }
Extract APIV3 documentation into single endpoints This does not differentiate further inside an endpoint and while useful (for e.g., work packages) we should discuss how the structure inside an endpoint should look like.
8 years ago
},
adding filter instance schemas
8 years ago
"total": 3,
"count": 3,
"_type": "Collection",
"_embedded":
{
"elements": [
{
"_links": {
"self": { "href": "/api/v3/versions/11" },
"definingProject": { "href": "/api/v3/projects/11" },
"availableInProjects": { "href": "/api/v3/versions/11/projects" }
},
"_type": "Version",
"id": 11,
"name": "v3.0 Alpha",
"description": {
"format": "plain",
"raw": "This version has a description",
"html": "This version has a description"
},
"startDate": "2014-11-20",
"endDate": null,
"status": "Open"
},
{
"_links": {
"self": { "href": "/api/v3/versions/12" },
"definingProject": { "href": "/api/v3/projects/11" },
"availableInProjects": { "href": "/api/v3/versions/12/projects" }
},
"_type": "Version",
"id": 12,
"name": "v2.0",
"description": {
"format": "plain",
"raw": "",
"html": ""
},
"startDate": null,
"endDate": null,
"status": "Closed"
},
{
"_links": {
"self": { "href": "/api/v3/versions/10" },
"definingProject": { "href": "/api/v3/projects/11" },
"availableInProjects": { "href": "/api/v3/versions/10/projects" }
},
"_type": "Version",
"id": 10,
"name": "v1.0",
"description": {
"format": "plain",
"raw": "",
"html": ""
},
"startDate": null,
"endDate": null,
"status": "Open"
}
]
}
Extract APIV3 documentation into single endpoints This does not differentiate further inside an endpoint and while useful (for e.g., work packages) we should discuss how the structure inside an endpoint should look like.
8 years ago
}
adding filter instance schemas
8 years ago
## List versions available in a project [GET]
This endpoint lists the versions that are *available* in a given project.
Note that due to sharing this might be more than the versions *defined* by that project.
Extract APIV3 documentation into single endpoints This does not differentiate further inside an endpoint and while useful (for e.g., work packages) we should discuss how the structure inside an endpoint should look like.
8 years ago
+ Parameters
adding filter instance schemas
8 years ago
+ project_id (required, integer, `1`) ... ID of the project whoose versions will be listed
Extract APIV3 documentation into single endpoints This does not differentiate further inside an endpoint and while useful (for e.g., work packages) we should discuss how the structure inside an endpoint should look like.
8 years ago
+ Response 200 (application/hal+json)
adding filter instance schemas
8 years ago
[Versions by Project][]
Extract APIV3 documentation into single endpoints This does not differentiate further inside an endpoint and while useful (for e.g., work packages) we should discuss how the structure inside an endpoint should look like.
8 years ago
+ Response 404 (application/hal+json)
adding filter instance schemas
8 years ago
Returned if the project does not exist or the client does not have sufficient permissions
Extract APIV3 documentation into single endpoints This does not differentiate further inside an endpoint and while useful (for e.g., work packages) we should discuss how the structure inside an endpoint should look like.
8 years ago
to see it.
adding filter instance schemas
8 years ago
**Required permission:** view work packages **or** manage versions (on given project)
Extract APIV3 documentation into single endpoints This does not differentiate further inside an endpoint and while useful (for e.g., work packages) we should discuss how the structure inside an endpoint should look like.
8 years ago
adding filter instance schemas
8 years ago
*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.*
Extract APIV3 documentation into single endpoints This does not differentiate further inside an endpoint and while useful (for e.g., work packages) we should discuss how the structure inside an endpoint should look like.
8 years ago
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
adding filter instance schemas
8 years ago
"message": "The specified project does not exist."
Extract APIV3 documentation into single endpoints This does not differentiate further inside an endpoint and while useful (for e.g., work packages) we should discuss how the structure inside an endpoint should look like.
8 years ago
}