TheDude
/
openproject
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #3276 from oliverguenther/feature/apiv3_revision_specification

Browse Source 
APIv3 blueprint: Add revisions endpoint
pull/3282/merge
Jan Sandbrink 9 years ago
parent 7b7ba7115e fc05dad2cf
commit 85209daf9b
1 changed files with 196 additions and 0 deletions
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 196
      doc/apiv3-documentation.apib

196
doc/apiv3-documentation.apib
Unescape View File

@ -2139,6 +2139,84 @@ For more details and all possible responses see the general specification of [Fo
"message": "The request body was not empty."
}
# Group Revisions
Revisions are sets of updates to files in the context of repositories linked in OpenProject.
## Linked Properties
| Link | Description | Type | Constraints | Supported operations |
|:----------------:| --------------------------------------------------------------------------------------------------| ------------- | ----------- | -------------------- |
| self | This revision | Revision | not null | READ |
| project | The project to which the revision belongs | Project | not null | READ |
| author | The user that added this revision, if the authorName was mapped to a user in OpenProject | User | | READ |
## Local Properties
| Property | Description | Type | Constraints | Supported operations |
|:--------------:| ------------------------------------------------------------------------------------------------------------------------------------------------------------| ----------- | ----------- | -------------------- |
| id | Revisions's id, assigned by OpenProject | Integer | x > 0 | READ |
| identifier | The SCM identifier of the revision (e.g. SHA hash) | String | not null | READ |
| authorName | The name of the author that committed this revision. Note that this name is retrieved from the repository and does not identify a user in OpenProject. | String | not null | READ |
| message | The commit message of the revision | Formattable | not null | READ |
| createdAt | The time this revision was committed to the repository | DateTime | not null | READ |
## Revision [/api/v3/revisions/{id}]
+ Model
+ Body
{
"_type": "Revision",
"_links": {
"self": {
"href": "/api/v3/revisions/1"
},
"project" {
"href": "/api/v3/projects/1"
},
"author": {
"href": "/api/v3/users/1"
},
},
"id": 1,
"identifier": "11f4b07dff4f4ce9548a52b7d002daca7cd63ec6",
"authorName": "Some Developer",
"message": {
"format": "plain",
"raw": "This revision provides new features\n\nAn elaborate description",
"html": "<p>This revision provides new features<br/><br/>An elaborate description</p>"
},
"createdAt": "2015-07-21T13:36:59Z"
}
## View revision [GET]
+ Parameters
+ id (required, integer, `1`) ... Revision id
+ Response 200 (application/hal+json)
[Revision][]
+ Response 404 (application/hal+json)
Returned if the revision does not exist or the client does not have sufficient permissions
to see it.
**Required permission:** view changesets for the project the repository is created in.
*Note: A client without sufficient permissions shall not be able to test for the existence of a revision.
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 revision does not exist."
}
# Group Schemas
## Linked Properties
@ -3156,6 +3234,7 @@ Note that due to sharing this might be more than the versions *defined* by that
| priority | The priority of the work package | Priority | not null | READ / WRITE | |
| project | The project to which the work package belongs | Project | not null | READ | |
| responsible | The person that is responsible for the overall outcome | User | | READ / WRITE | |
| revisions | Revisions that are referencing the work package | Revision | | READ | **Permission** view changesets |
| status | The current status of the work package | Status | not null | READ / WRITE | |
| timeEntries | All time entries logged on the work package. Please note that this is a link to an HTML resource for now and as such, the link is subject to change. | N/A | | READ | **Permission** view time entries |
| type | The type of the work package | Type | not null | READ / WRITE | |
@ -3251,6 +3330,9 @@ the human readable name of custom fields.*
"href": "/api/v3/users/23",
"title": "Laron Leuschke - Alaina5788"
},
"revisions": {
"href": "/api/v3/work_packages/1528/revisions"
},
"assignee": {
"href": "/api/v3/users/11",
"title": "Emmie Okuneva - Adele5450"
@ -3937,6 +4019,120 @@ Gets a list of users that are able to be watchers of the specified work package.
"message": "The specified work package does not exist."
}
## Revisions [/api/v3/work_packages/{id}/revisions]
+ Model
+ Body
{
"_links": {
"self": { "href": "/api/v3/work_packages/42/revisions" },
"filter": {
"href": "/api/v3/work_packages/42/revisions",
"templated": true
}
},
"total": 2,
"count": 2,
"_type": "Collection",
"_embedded": {
"elements": [
{
"_type": "Revision",
"_links": {
"self": {
"href": "/api/v3/revisions/13",
},
"project": {
"href": "/api/v3/projects/1",
"title": "A Test Project
},
"author": {
"href": "/api/v3/users/1",
"title": "John Sheppard - j.sheppard"
}
},
"id": 13,
"identifier": "11f4b07dff4f4ce9548a52b7d002daca7cd63ec6",
"authorName": "John Sheppard",
"message": {
"format": "plain",
"raw": "This revision provides new features\n\nAn elaborate description",
"html": "<p>This revision provides new features<br/><br/>An elaborate description</p>"
},
"createdAt": "2015-07-21T13:36:59Z",
},
{
"_type": "Revision",
"_links": {
"self": {
"href": "/api/v3/revisions/14",
},
"project": {
"href": "/api/v3/projects/1",
"title": "A Test Project
},
"author": {
"href": "/api/v3/users/2",
"title": "Jim Sheppard - j.sheppard"
}
},
"id": 13,
"identifier": "029ed72a3b7b7c4ab332b1f6eaa6576e7c946059",
"authorName": "j1msheppard",
"message": {
"format": "plain",
"raw": "This revision fixes some stuff\n\nMore information here",
"html": "<p>This revision fixes some stuff<br/><br/>More information here</p>"
},
"createdAt": "2015-06-30T08:47:00Z",
}]
}
}
## Revisions [GET]
Gets a list of revisions that are linked to this work package, e.g., because it is referenced in the commit message of the revision.
+ Parameters
+ id (required, integer, `1`) ... work package id
+ Response 200 (application/hal+json)
[Revisions][]
+ Response 403 (application/hal+json)
Returned if the client does not have sufficient permissions.
**Required permission:** view changesets of the project this work package is contained in
*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 linked revisions for this work package."
}
+ Response 404 (application/hal+json)
Returned if the project does not exist or the client does not have sufficient permissions to see it.
**Required permission:** view project
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The specified project does not exist."
}
## Comment WorkPackage [/api/v3/work_packages/{id}/activities]
## Comment work package [POST]

Write Preview
Loading…
Cancel
Save