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

Merge pull request #2237 from opf/feature/clean_spec_tables

Browse Source 
Cleanup API specification tables
pull/2242/head
Jan Sandbrink 10 years ago
parent 8ab4408b97 c07874a10c
commit ede8df14f0
1 changed files with 142 additions and 133 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. 205
      doc/apiv3-documentation.apib

205
doc/apiv3-documentation.apib
Unescape View File

@ -181,6 +181,15 @@ If the *Formatable* is marked as **read only**, the `raw` attribute also becomes
"html": "I <strong>am</strong> formatted!" "html": "I <strong>am</strong> formatted!"
} }
# Dates, Times and Durations
Representation of time related values in this API is done according to [ISO 8601](http://en.wikipedia.org/wiki/ISO_8601).
In this specification the following terms will be used as type specifiers (e.g. in tables):
* `Date` - refers to an ISO 8601 date, e.g. "2014-05-21"
* `DateTime` - refers to an ISO 8601 combined date and time, e.g. "2014-05-21T13:37:00Z"
* `Duration` - refers to an ISO 8601 duration, e.g. "P1DT18H"
# Group Collections # Group Collections
Whenever a client calls a resource that can return more than one element, it will receive a collection of elements. Whenever a client calls a resource that can return more than one element, it will receive a collection of elements.
@ -326,13 +335,13 @@ Cursor based pagination is therefore less suited for use cases where you want to
# Group Activities # Group Activities
## Properties: ## Properties:
| Property | Description | Type | Constraints | Example | Supported operations | | Property | Description | Type | Constraints | Supported operations |
|:---------:|-------------| ---- | ----------- | ------- | -------------------- | | :---------: | ------------- | ---- | ----------- | -------------------- |
| id | Activity id | Integer | Must be a positive integer | 12 | READ | | id | Activity id | Integer | x > 0 | READ |
| version | Activity version | Integer | Must be a positive integer | 31 | READ | | version | Activity version | Integer | x > 0 | READ |
| comment | | Formatable | | | READ / WRITE | | comment | | Formatable | | READ / WRITE |
| details | | Array of Formatable | | | READ | | details | | Array of Formatable | | READ |
| createdAt | Time of creation | DateTime | ISO 8601 combined date and time | 2014-05-21T13:37:00Z | READ | | createdAt | Time of creation | DateTime | | READ |
Activity can be either _type Activity or _type Activity::Comment. Activity can be either _type Activity or _type Activity::Comment.
@ -442,16 +451,16 @@ Updates an activity's comment and, on success, returns the updated activity.
# Group Attachments # Group Attachments
## Properties: ## Properties:
| Property | Description | Type | Constraints | Example | Supported operations | | Property | Description | Type | Constraints | Supported operations |
|:---------:|-------------| ---- | ----------- | ------- | -------------------- | | :---------: | ------------- | ---- | ----------- | -------------------- |
| id | Attachment's id | Integer | Must be a positive integer | 12 | READ | | id | Attachment's id | Integer | x > 0 | READ |
| fileName | | String | | dolor_sit_amet | READ | | fileName | | String | | READ |
| diskFileName | | String | | dolor_sit_amet | READ | | diskFileName | | String | | READ |
| description | | String | | Lorem ipsum dolor ... | READ | | description | | String | | READ |
| contentType | | String | | application/binary | READ | | contentType | | String | | READ |
| digest | | String | | | READ | | digest | | String | | READ |
| downloads | | Integer | | | READ | | downloads | | Integer | | READ |
| createdAt | Time of creation | DateTime | ISO 8601 combined date and time | 2014-05-21T13:37:00Z | READ | | createdAt | Time of creation | DateTime | | READ |
## Attachment [/api/v3/attachments/{id}] ## Attachment [/api/v3/attachments/{id}]
@ -497,10 +506,10 @@ Updates an activity's comment and, on success, returns the updated activity.
# Group Categories # Group Categories
## Properties ## Properties
| Property | Description | Type | Constraints | Example | Supported operations | | Property | Description | Type | Constraints | Supported operations |
|:--------:|-------------| ------- | ----------- | ------- | -------------------- | | :--------: | ------------- | ------- | ----------- | -------------------- |
| id | Category id | Integer | Must be a positive integer | 12 | READ | | id | Category id | Integer | x > 0 | READ |
| name | Category name | String | | Category Name | READ | | name | Category name | String | | READ |
## Categories by Project [/api/v3/projects/{project_id}/categories] ## Categories by Project [/api/v3/projects/{project_id}/categories]
@ -559,7 +568,7 @@ Subsequent calls to the form should contain a single JSON object as described by
## Actions: ## Actions:
| Link | Description | Condition | | Link | Description | Condition |
|:-------------------:|-----------------------------------------------------------------------| -------------------------------- | |:-------------------:| --------------------------------------------------------------------- | -------------------------------- |
| validate | Validate changes, show errors and allowed values for changed resource | | | validate | Validate changes, show errors and allowed values for changed resource | |
| commit | Actually perform changes to the resource | form content is valid | | commit | Actually perform changes to the resource | form content is valid |
| previewMarkup | Post markup (e.g. textile) here to receive an HTML-rendered response | | | previewMarkup | Post markup (e.g. textile) here to receive an HTML-rendered response | |
@ -599,17 +608,17 @@ and objects describing the corresponding property as values. The values are call
**Linked Properties** **Linked Properties**
| Property | Description | Example | | Property | Description |
|:--------------:|----------------------------------------------------------------| ------------- | |:--------------:|----------------------------------------------------------------|
| allowed_values | List of resources that are assignable by the current user. | `{ href: "/api/v3/statuses" }` | | allowed_values | List of resources that are assignable by the current user. |
**Properties** **Properties**
| Property | Description | Example | Default | | Property | Description | Default |
|:--------------:|----------------------------------------------------------------| ------------- | ------- | |:--------------:|----------------------------------------------------------------| ------- |
| type | The data type of the properties values | String | | | type | The data type of the properties values | |
| required | If true every request **must** contain this property | true | false | | required | If true every request **must** contain this property | false |
| writable | If false it is not allowed to **change** the properties value | false | true | | writable | If false it is not allowed to **change** the properties value | true |
**Remarks** **Remarks**
@ -860,13 +869,13 @@ The request body is the actual string that shall be rendered as HTML string.
| self | This priority | Priority | not null | READ | | self | This priority | Priority | not null | READ |
## Properties ## Properties
| Property | Description | Type | Constraints | Example | Supported operations | | Property | Description | Type | Constraints | Supported operations |
|:---------:| ------------------------------------------- | ---------- | ----------- | ---------- | -------------------- | | :---------: | ------------------------------------------- | ---------- | ----------- | -------------------- |
| id | Priority id | Integer | x > 0 | 12 | READ | | id | Priority id | Integer | x > 0 | READ |
| name | Priority name | String | not empty | High | READ | | name | Priority name | String | not empty | READ |
| position | Sort index of the priority | Integer | x > 0 | 2 | READ | | position | Sort index of the priority | Integer | x > 0 | READ |
| isDefault | Indicates whether this is the default value | Boolean | | true | READ | | isDefault | Indicates whether this is the default value | Boolean | | READ |
| isActive | Indicates whether the priority is available | Boolean | | true | READ | | isActive | Indicates whether the priority is available | Boolean | | READ |
## Priorities [/api/v3/priorities] ## Priorities [/api/v3/priorities]
@ -994,21 +1003,21 @@ The request body is the actual string that shall be rendered as HTML string.
## Linked Properties: ## Linked Properties:
| Link | Description | Type | Constraints | Supported operations | | Link | Description | Type | Constraints | Supported operations |
|:------:|-------------| ---- | ----------- | -------------------- | | :------: | ------------- | ---- | ----------- | -------------------- |
| self | This project | Project | not null | READ | | self | This project | Project | not null | READ |
| categories | Categories available in this project | Categories | not null | READ | | categories | Categories available in this project | Categories | not null | READ |
| versions | Versions available in this project | Versions | not null | READ | | versions | Versions available in this project | Versions | not null | READ |
## Properties: ## Properties:
| Property | Description | Type | Constraints | Example | Supported operations | | Property | Description | Type | Constraints | Supported operations |
|:---------:|-------------| ---- | ----------- | ------- | -------------------- | | :---------: | ------------- | ---- | ----------- | -------------------- |
| id | Projects's id | Integer | Must be a positive integer | 12 | READ | | id | Projects's id | Integer | x > 0 | READ |
| identifier | | String | | project_identifier | READ | | identifier | | String | | READ |
| name | | String | | Project example | READ | | name | | String | | READ |
| description | | String | | Lorem ipsum dolor sit amet | READ | | description | | String | | READ |
| homepage | | String | | http://openproject.com | READ | | homepage | | String | | READ |
| createdAt | Time of creation | DateTime | ISO 8601 combined date and time | 2014-05-21T13:37:00Z | READ | | createdAt | Time of creation | DateTime | | READ |
| updatedAt | Time of the most recent change to the project | DateTime | ISO 8601 combined date and time | 2014-05-21T17:13:37Z| READ | | updatedAt | Time of the most recent change to the project | DateTime | | READ |
## Project [/api/v3/projects/{id}] ## Project [/api/v3/projects/{id}]
@ -1048,17 +1057,17 @@ The request body is the actual string that shall be rendered as HTML string.
# Group Queries # Group Queries
## Properties: ## Properties:
| Property | Description | Type | Constraints | Example | Supported operations | | Property | Description | Type | Constraints | Supported operations |
|:---------:|-------------| ---- | ----------- | ------- | -------------------- | | :---------: | ------------- | ---- | ----------- | -------------------- |
| id | Query id | Integer | Must be a positive integer | 12 | READ | | id | Query id | Integer | x > 0 | READ |
| name | Query name | String | | My work packages query | READ | | name | Query name | String | | READ |
| filters | | String | | | READ | | filters | | String | | READ |
| isPublic | | Boolean | | true | READ | | isPublic | | Boolean | | READ |
| columnNames | | String | | | READ | | columnNames | | String | | READ |
| sortCriteria | | String | | | READ | | sortCriteria | | String | | READ |
| groupBy | | String | | | READ | | groupBy | | String | | READ |
| displaySums | | Boolean | | true | READ | | displaySums | | Boolean | | READ |
| isStarred | | Boolean | | true | READ | | isStarred | | Boolean | | READ |
## Query [/api/v3/queries/{id}] ## Query [/api/v3/queries/{id}]
@ -1295,14 +1304,14 @@ The request body is the actual string that shall be rendered as HTML string.
| self | This status | Status | not null | READ | | self | This status | Status | not null | READ |
## Properties ## Properties
| Property | Description | Type | Constraints | Example | Supported operations | | Property | Description | Type | Constraints | Supported operations |
|:--------:|-------------| ------- | ----------- | ------- | -------------------- | | :--------: | ------------- | ------- | ----------- | -------------------- |
| id | Status id | Integer | Must be a positive integer | 12 | READ | | id | Status id | Integer | x > 0 | READ |
| name | Status name | String | | Closed | READ | | name | Status name | String | | READ |
| position | Sort index of the status | Integer | | 1 | READ | | position | Sort index of the status | Integer | | READ |
| isDefault| | Boolean | | true | READ | | isDefault | | Boolean | | READ |
| isClosed | are tickets of this status considered closed? | Boolean | | true | READ | | isClosed | are tickets of this status considered closed? | Boolean | | READ |
| defaultDoneRatio | The percentageDone being applied when changing to this status | Integer | 0 <= x <= 100 | 50 | READ | | defaultDoneRatio | The percentageDone being applied when changing to this status | Integer | 0 <= x <= 100 | READ |
## Statuses [/api/v3/statuses] ## Statuses [/api/v3/statuses]
@ -1491,17 +1500,17 @@ The request body is the actual string that shall be rendered as HTML string.
# Group Users # Group Users
## Properties: ## Properties:
| Property | Description | Type | Constraints | Example | Supported operations | | Property | Description | Type | Constraints | Supported operations |
|:---------:|-------------| ---- | ----------- | ------- | -------------------- | | :---------: | ------------- | ---- | ----------- | -------------------- |
| id | User's id | Integer | Must be a positive integer | 12 | READ | | id | User's id | Integer | x > 0 | READ |
| login | User's login name | String | | j.sheppard | READ | | login | User's login name | String | | READ |
| firstName | User's first name | String | | John | READ | | firstName | User's first name | String | | READ |
| lastName | User's last name | String | | Sheppard | READ | | lastName | User's last name | String | | READ |
| name | User's full name, formatting depends on instance settings | String | | Sheppard, John | READ | | name | User's full name, formatting depends on instance settings | String | | READ |
| mail | User's email | String | | shep@mail.com | READ | | mail | User's email | String | | READ |
| avatar | URL to user's avatar | String | | https://gravatar/avatar | READ | | avatar | URL to user's avatar | String | | READ |
| createdAt | Time of creation | DateTime | ISO 8601 combined date and time | 2014-05-21T13:37:00Z | READ | | createdAt | Time of creation | DateTime | | READ |
| updatedAt | Time of the most recent change to the user | DateTime | ISO 8601 combined date and time | 2014-05-21T17:13:37Z| READ | | updatedAt | Time of the most recent change to the user | DateTime | | READ |
## User [/api/v3/users/{id}] ## User [/api/v3/users/{id}]
@ -1539,10 +1548,10 @@ The request body is the actual string that shall be rendered as HTML string.
# Group Versions # Group Versions
## Properties ## Properties
| Property | Description | Type | Constraints | Example | Supported operations | | Property | Description | Type | Constraints | Supported operations |
|:--------:|-------------| ------- | ----------- | ------- | -------------------- | | :--------: | ------------- | ------- | ----------- | -------------------- |
| id | Version id | Integer | Must be a positive integer | 12 | READ | | id | Version id | Integer | x > 0 | READ |
| name | Version name | String | | Version 1.0 | READ | | name | Version name | String | | READ |
## Versions by Project [/api/v3/projects/{project_id}/versions] ## Versions by Project [/api/v3/projects/{project_id}/versions]
@ -1592,7 +1601,7 @@ The request body is the actual string that shall be rendered as HTML string.
## Actions: ## Actions:
| Link | Description | Condition | | Link | Description | Condition |
|:-------------------:|----------------------------------------------------------------------| -------------------------------- | |:-------------------:|----------------------------------------------------------------------| --------------------------------- |
| update | Form endpoint that aids in preparing and performing edits on a WP | **Permission**: edit work package | | update | Form endpoint that aids in preparing and performing edits on a WP | **Permission**: edit work package |
| updateImmediately | Directly perform edits on a work package | **Permission**: edit work package | | updateImmediately | Directly perform edits on a work package | **Permission**: edit work package |
| watch | Add current user to WP watchers | logged in; not watching | | watch | Add current user to WP watchers | logged in; not watching |
@ -1602,7 +1611,7 @@ The request body is the actual string that shall be rendered as HTML string.
## Linked Properties: ## Linked Properties:
| Link | Description | Type | Constraints | Supported operations | Condition | | Link | Description | Type | Constraints | Supported operations | Condition |
|:------------:|---------------------------------------------------------| ----------- | ----------- | -------------------- | -------------------------------- | | :------------: | --------------------------------------------------------- | ----------- | ----------- | -------------------- | -------------------------------- |
| self | This work package | WorkPackage | not null | READ | | | self | This work package | WorkPackage | not null | READ | |
| author | The person that created the work package | User | not null | READ | | | author | The person that created the work package | User | not null | READ | |
| assignee | The person that is intended to work on the work package | User | | READ / WRITE | | | assignee | The person that is intended to work on the work package | User | | READ / WRITE | |
@ -1613,21 +1622,21 @@ The request body is the actual string that shall be rendered as HTML string.
## Properties: ## Properties:
| Property | Description | Type | Constraints | Example | Supported operations | Condition | | Property | Description | Type | Constraints | Supported operations | Condition |
| :---------: | ------------- | ---- | ----------- | ------- | -------------------- | -------------------- | | :--------------: | ------------------------------------------------------ | ---------- | ---------------------------------------------------------------------------- | -------------------- | -------------------------------- |
| id | Work package id | Integer | Must be a positive integer | 12 | READ | | | id | Work package id | Integer | x > 0 | READ | |
| lockVersion | The version of the item as used for optimistic locking | Integer | | 12 | READ | | | lockVersion | The version of the item as used for optimistic locking | Integer | | READ | |
| subject | Work package subject | String | not null; 1 <= length <= 255 | Refactor projecs module | READ / WRITE | | | subject | Work package subject | String | not null; 1 <= length <= 255 | READ / WRITE | |
| type | | String | **REQUIRED** Must be one of the types enabled for the current work package's project | Feature | READ | | | type | Name of the work package's type | String | not null | READ | |
| description | The work package description | Formatable | | | READ / WRITE | | | description | The work package description | Formatable | | READ / WRITE | |
| parentId | Parent work package id | Integer | Must be an id of an existing and visible (in respect to the API user) work package | 42 | READ / WRITE | | | parentId | Parent work package id | Integer | Must be an id of an existing and visible (for the current user) work package | READ / WRITE | |
| startDate | | Date | ISO 8601 date; must be equal or greater than the soonest possible start date | 2014-05-21 | READ / WRITE | | | startDate | | Date | must be equal or greater than the soonest possible start date | READ / WRITE | |
| dueDate | | Date | ISO 8601 date; must be greater then start date | 2014-05-22 | READ / WRITE | | | dueDate | | Date | must be greater than start date | READ / WRITE | |
| estimatedTime | | Duration | ISO 8601 duration | P1DT18H | READ | | | estimatedTime | | Duration | | READ | |
| spentTime | | Duration | ISO 8601 duration | PT1H | READ | **Permission** view time entries | | spentTime | | Duration | | READ | **Permission** view time entries |
| percentageDone | | Integer | Must be an integer between 0 and 100 | 50 | READ | | | percentageDone | | Integer | 0 <= x <= 100 | READ | |
| createdAt | Time of creation | DateTime | ISO 8601 combined date and time | 2014-05-21T13:37:00Z | READ | | | createdAt | Time of creation | DateTime | | READ | |
| updatedAt | Time of the most recent change to the work package | DateTime | ISO 8601 combined date and time | 2014-05-21T17:13:37Z | READ | | | updatedAt | Time of the most recent change to the work package | DateTime | | READ | |
## WorkPackage [/api/v3/work_packages/{id}{?notify}] ## WorkPackage [/api/v3/work_packages/{id}{?notify}]

Write Preview
Loading…
Cancel
Save