mirror of
https://github.com/opf/openproject.git
synced 2026-06-14 03:30:14 +00:00
as-op
96 lines
4.2 KiB
YAML
96 lines
4.2 KiB
YAML
# /api/v3/programs
|
|
---
|
|
get:
|
|
summary: List programs
|
|
operationId: list_programs
|
|
tags:
|
|
- Programs
|
|
description: Returns a collection of programs. The collection can be filtered via
|
|
query parameters similar to how work packages are filtered. In addition to the
|
|
provided filter, the result set is always limited to only contain programs the
|
|
client is allowed to see.
|
|
parameters:
|
|
- name: filters
|
|
schema:
|
|
type: string
|
|
in: query
|
|
required: false
|
|
description: |-
|
|
JSON specifying filter conditions.
|
|
Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint.
|
|
Currently supported filters are:
|
|
|
|
+ active: based on the active property of the program
|
|
+ ancestor: filters programs by their ancestor. A program is not considered to be its own ancestor.
|
|
+ available_project_attributes: filters programs based on the activated project attributes.
|
|
+ created_at: based on the time the program was created
|
|
+ favorited: based on the favorited property of the program
|
|
+ id: based on programs' id.
|
|
+ latest_activity_at: based on the time the last activity was registered on a program.
|
|
+ name_and_identifier: based on both the name and the identifier.
|
|
+ parent_id: filters programs by their parent.
|
|
+ principal: based on members of the program.
|
|
+ project_phase_any: based on the project phases active in a program.
|
|
+ project_status_code: based on status code of the program
|
|
+ storage_id: filters programs by linked storages
|
|
+ storage_url: filters programs by linked storages identified by the host url
|
|
+ type_id: based on the types active in a program.
|
|
+ user_action: based on the actions the current user has in the program.
|
|
+ visible: based on the visibility for the user (id) provided as the filter value. This filter is useful for admins to identify the programs visible to a user.
|
|
|
|
There might also be additional filters based on the custom fields that have been configured.
|
|
|
|
Each defined lifecycle step will also define a filter in this list endpoint. Given that the elements are not
|
|
static but rather dynamically created on each OpenProject instance, a list cannot be provided. Those filters follow the schema:
|
|
+ project_start_gate_[id]: a filter on a project phase's start gate active in a program. The id is the id of the phase the gate belongs to.
|
|
+ project_finish_gate_[id]: a filter on a project phase's finish gate active in a program. The id is the id of the phase the gate belongs to.
|
|
+ project_phase_[id]: a filter on a project phase active in a program. The id is the id of the phase queried for.
|
|
example: '[{ "ancestor": { "operator": "=", "values": ["1"] }" }]'
|
|
- name: sortBy
|
|
schema:
|
|
type: string
|
|
in: query
|
|
required: false
|
|
description: |-
|
|
JSON specifying sort criteria.
|
|
Currently supported orders are:
|
|
|
|
+ id
|
|
+ name
|
|
+ typeahead (sorting by hierarchy and name)
|
|
+ created_at
|
|
+ public
|
|
+ latest_activity_at
|
|
+ required_disk_space
|
|
|
|
There might also be additional orders based on the custom fields that have been configured.
|
|
example: '[["id", "asc"]]'
|
|
- name: select
|
|
schema:
|
|
type: string
|
|
in: query
|
|
required: false
|
|
description: |-
|
|
Comma separated list of properties to include.
|
|
example: 'total,elements/identifier,elements/name'
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
content:
|
|
application/hal+json:
|
|
schema:
|
|
$ref: '../components/schemas/program_collection_model.yml'
|
|
examples:
|
|
'simple program collection':
|
|
$ref: '../components/examples/program_collection.yml'
|
|
'400':
|
|
description: Returned if the client sends invalid request parameters e.g. filters
|
|
content:
|
|
application/hal+json:
|
|
schema:
|
|
$ref: '../components/schemas/error_response.yml'
|
|
example:
|
|
_type: Error
|
|
errorIdentifier: urn:openproject-org:api:v3:errors:InvalidQuery
|
|
message: Filters Invalid filter does not exist.
|