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.
30204 Commits
139 Branches
203 Tags
1.2 GiB
 
 
 
 
 
 
Tag: Branch: Tree: 781d1309c3
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '781d1309c3'
${ noResults }
openproject/doc/apiv3/endpoints/queries.apib

454 lines
16 KiB
Raw Blame History

# Group Queries
| Link | Description | Type | Constraints | Supported operations | Condition |
| :----------------: | ------------------------------------------------------------------------ | ------------ | ------------ | --------------------- | ----------------------------------------- |
| self | This query | Query | not null | READ | |
| user | The user that owns this query | User | not null | READ | |
| project | The project on which this query operates | Project | | READ | |
## Local Properties
| Property | Description | Type | Constraints | Supported operations |
| :--------------: | ------------------------------------------------------ | ----------- | -------------------------------- | -------------------- |
| id | Query id | Integer | x > 0 | READ |
| name | Query name | String | | READ |
| filters | An object describing the queries filter conditions | Object | | READ |
| columnNames | Ordered list of properties to be shown in this query | String[] | | READ |
| sortCriteria | An object describing the sorting rules of this query | Object | | READ |
| groupBy | The property to group results of this query by | String | | READ |
| displaySums | Should sums (of supported properties) be shown? | Boolean | | READ |
| isPublic | Can users besides the owner see the query? | Boolean | | READ |
| isStarred | Should the query be highlighted to the user? | Boolean | | READ |
A query that is not assigned to a project (`"project": null`) is called a global query. Global queries filter work packages regarless of the project they are assigned to. As such, a different set of filters exists for those queries.
## Query [/api/v3/queries/{id}]
+ Model
+ Body
{
"_type": "Query",
"_links": {
"self": {
"href": "/api/v3/queries/2",
"title": "My work packages"
},
"project": {
"href": "/api/v3/projects/1",
"title": "A project"
},
"user": {
"href": "/api/v3/users/1",
"title": "John Sheppard"
}
},
"id": 2,
"name": "My work packages",
"filters": [
{
"status": {
"operator": "o",
"values": null
}
},
{
"assignee": {
"operator": "=",
"values": [
"me"
]
}
}
],
"isPublic": false,
"columnNames": [
"type",
"status",
"priority",
"subject",
"assignee"
],
"sortCriteria": [
[
"parent",
"desc"
]
],
"groupBy": null,
"displaySums": false,
"isStarred": true
}
## View query [GET]
*might be subject to change in the future*
+ Parameters
+ id (required, integer, `1`) ... Query id
+ Response 200 (application/hal+json)
[Query][]
+ Response 404 (application/hal+json)
Returned if the query does not exist or the client does not have sufficient permissions to see it.
**Required condition:** query belongs to user or query is public
**Required permission:** view work package in queries project
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The specified query does not exist."
}
## Delete query [DELETE]
+ Parameters
+ id (required, integer, `1`) ... Query id
+ Response 204
+ Response 403 (application/hal+json)
Returned if the client does not have sufficient permissions.
**Required permission:** for own queries none; for public queries: manage public queries
*Note that you will only receive this error, if you are at least allowed to see the corresponding query.*
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not authorized to access this resource."
}
+ Response 404 (application/hal+json)
Returned if the query does not exist or the client does not have sufficient permissions to see it.
**Required condition:** query belongs to user or query is public
**Required permission:** view work package in queries project
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The requested resource could not be found."
}
## Star Query [/api/v3/queries/{id}/star]
+ Model
+ Body
{
"_type": "Query",
"_links": {
"self": {
"href": "/api/v3/queries/2",
"title": "My work packages"
},
"project": {
"href": "/api/v3/projects/1",
"title": "Lorem ipsum"
},
"user": {
"href": "/api/v3/users/1",
"title": "John Sheppard - admin"
}
},
"id": 2,
"name": "My work packages",
"filters": [
{
"status": {
"operator": "o",
"values": null
}
},
{
"assignee": {
"operator": "=",
"values": [
"me"
]
}
}
],
"isPublic": false,
"columnNames": [
"type",
"status",
"priority",
"subject",
"assignee"
],
"sortCriteria": [
[
"parent",
"desc"
]
],
"groupBy": null,
"displaySums": false,
"isStarred": true
}
## Star query [PATCH]
+ Parameters
+ id (required, integer, `1`) ... Query id
+ Response 200 (application/hal+json)
[Star Query][]
+ Response 400 (application/hal+json)
Occurs when the client did not send an empty request body.
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
"message": "The request body was not empty."
}
+ Response 403 (application/hal+json)
Returned if the client does not have sufficient permissions.
**Required permission:** for own queries none; for public queries: manage public queries
*Note that you will only receive this error, if you are at least allowed to see the corresponding query.*
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not allowed to star this query."
}
+ Response 404 (application/hal+json)
Returned if the query does not exist or the client does not have sufficient permissions to see it.
**Required condition:** query belongs to user or query is public
**Required permission:** view work package in queries project
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The specified query does not exist."
}
## Unstar Query [/api/v3/queries/{id}/unstar]
+ Model
+ Body
{
"_type": "Query",
"_links": {
"self": {
"href": "/api/v3/queries/2",
"title": "My work packages"
},
"project": {
"href": "/api/v3/projects/1",
"title": "Lorem ipsum"
},
"user": {
"href": "/api/v3/users/1",
"title": "John Sheppard - admin"
}
},
"id": 2,
"name": "My work packages",
"filters": [
{
"status": {
"operator": "o",
"values": null
}
},
{
"assignee": {
"operator": "=",
"values": [
"me"
]
}
}
],
"isPublic": false,
"columnNames": [
"type",
"status",
"priority",
"subject",
"assignee"
],
"sortCriteria": [
[
"parent",
"desc"
]
],
"groupBy": null,
"displaySums": false,
"isStarred": false
}
## Unstar query [PATCH]
+ Parameters
+ id (required, integer, `1`) ... Query id
+ Response 200 (application/hal+json)
[Unstar Query][]
+ Response 400 (application/hal+json)
Occurs when the client did not send an empty request body.
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
"message": "The request body was not empty."
}
+ Response 403 (application/hal+json)
Returned if the client does not have sufficient permissions.
**Required permission:** for own queries none; for public queries: manage public queries
*Note that you will only receive this error, if you are at least allowed to see the corresponding query.*
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not allowed to unstar this query."
}
+ Response 404 (application/hal+json)
Returned if the query does not exist or the client does not have sufficient permissions to see it.
**Required condition:** query belongs to user or query is public
**Required permission:** view work package in queries project
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The specified query does not exist."
}
##Queries [/api/v3/queries{?filters}]
+ Model
+ Body
{
"_links":
{
"self":
{
"href": "/api/v3/queries"
}
},
"total": 1,
"count": 1,
"_type": "Collection",
"_embedded":
{
"elements": [
{
"_type": "Query",
"_links": {
"self": {
"href": "/api/v3/queries/2",
"title": "My work packages"
},
"project": {
"href": null
},
"user": {
"href": "/api/v3/users/1",
"title": "John Sheppard"
}
},
"id": 2,
"name": "My work packages",
"filters": [],
"isPublic": false,
"columnNames": [
"type",
"status",
"subject"
],
"sortCriteria": [
[
"parent",
"desc"
]
],
"groupBy": null,
"displaySums": false,
"isStarred": true
}
]
}
}
## List queries [GET]
Returns a collection of queries. The collection can be filtered via query parameters similar to how work packages are filtered. Please note however, that the filters are applied to the queries and not to the work packages the filters in turn might return.
+ Parameters
+ filters (optional, string, `[{ "project_id": { "operator": "!*", "values": null }" }]`) ... JSON specifying filter conditions.
Accepts the same format as returned by the [queries](#queries) endpoint.
Currently supported filters are:
+ project: filters queries by the project they are assigned to. If the project filter is passed with the `!*` (not any) operator, global queries are returned.
+ Response 200 (application/hal+json)
[Queries][]
+ Response 403 (application/hal+json)
Returned if the client does not have sufficient permissions to see queries.
**Required permission:** view work packages or manage public queries in any project
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not allowed to see the queries."
}