diff --git a/.editorconfig b/.editorconfig index f62bf958132..9775128ca33 100644 --- a/.editorconfig +++ b/.editorconfig @@ -540,3 +540,6 @@ ij_typescript_var_declaration_wrap = normal ij_typescript_while_brace_force = never ij_typescript_while_on_new_line = false ij_typescript_wrap_comments = false + +[docs/api/**/*.yml] +trim_trailing_whitespace = false \ No newline at end of file diff --git a/docs/api/README.md b/docs/api/README.md index 89e6332df14..b25cee413b4 100644 --- a/docs/api/README.md +++ b/docs/api/README.md @@ -24,7 +24,7 @@ The API v3 is a general purpose API supporting multiple use cases. While by no means complete, a whole lot of different scenarios can be automatised which otherwise would have to be carried out by hand via the UI. Examples for this include managing work packages, projects and users. ---> [Go to OpenProject API](./introduction/) +➔ [Go to OpenProject API](./introduction/) ## BCF v2.1 @@ -32,4 +32,4 @@ This API supports BCF management in the context of BIM projects. While this API supports way less use cases than the more generic *API v3* it is compatible with the generic specification of a BCF API as [defined by the standard](https://github.com/buildingSMART/BCF-API/blob/release_2_1/README.md). This, clients implementing the specification can manage topics and viewpoints. ---> [Go to BCF API](./bcf-rest-api/) +➔ [Go to BCF API](./bcf-rest-api/) diff --git a/docs/api/apiv3/README.md b/docs/api/apiv3/README.md index 06e08ef91bd..a4455e78e97 100644 --- a/docs/api/apiv3/README.md +++ b/docs/api/apiv3/README.md @@ -4,11 +4,9 @@ _Status: under development_ The documentation for APIv3 is written according to the [OpenAPI 3.0 Specification](https://swagger.io/specification/). -The generated APIv3 documentation is built regular on the `dev` branch and can be found at: [opf.github.io/apiv3-doc/](opf.github.io/apiv3-doc/). - The file in the repository is split up into many files. Some OAS (OpenAPI Specification) do not support that. -You can retrieve the complete, singular file from any OpenProject server under under `/api/v3/spec.json` or `/api/v3/spec.yml`. -Additionally there is a rake task that outputs the specification as a whole as well, either as json or yaml depending +You can retrieve the complete, singular file from any OpenProject server under `/api/v3/spec.json` or `/api/v3/spec.yml`. +Additionally, there is a rake task that outputs the specification as a whole as well, either as json or yaml depending on the given output file name: ``` diff --git a/docs/api/apiv3/client-libraries/README.md b/docs/api/apiv3/client-libraries/README.md index c7fe4776616..c8d90470444 100644 --- a/docs/api/apiv3/client-libraries/README.md +++ b/docs/api/apiv3/client-libraries/README.md @@ -9,7 +9,7 @@ If you need help developing a client library you can [contact us](mailto:support ## JavaScript / TypeScript -* [op-client](https://www.npmjs.com/package/op-client): "Client library for OpenProject server. Works both on Node.js and browser." +* [op-client](https://www.npmjs.com/package/op-client): Client library for OpenProject server. Works both on Node.js and browser. ## Excel diff --git a/docs/api/apiv3/components/schemas/available_projects_for_memberships_model.yml b/docs/api/apiv3/components/schemas/available_projects_for_memberships_model.yml index cb7e7be4bbf..19d693ff563 100644 --- a/docs/api/apiv3/components/schemas/available_projects_for_memberships_model.yml +++ b/docs/api/apiv3/components/schemas/available_projects_for_memberships_model.yml @@ -16,7 +16,7 @@ example: href: "/api/v3/projects/6" title: A project editWorkPackage: - href: "/api/v3//work_packages/{work_package_id}/form" + href: "/api/v3/work_packages/{id}/form" templated: true method: post createWorkPackage: diff --git a/docs/api/apiv3/components/schemas/available_projects_for_versions_model.yml b/docs/api/apiv3/components/schemas/available_projects_for_versions_model.yml index 57f4a154469..266147790ef 100644 --- a/docs/api/apiv3/components/schemas/available_projects_for_versions_model.yml +++ b/docs/api/apiv3/components/schemas/available_projects_for_versions_model.yml @@ -16,7 +16,7 @@ example: href: "/api/v3/projects/6" title: A project editWorkPackage: - href: "/api/v3//work_packages/{work_package_id}/form" + href: "/api/v3/work_packages/{id}/form" templated: true method: post createWorkPackage: diff --git a/docs/api/apiv3/components/schemas/available_projects_for_work_package_model.yml b/docs/api/apiv3/components/schemas/available_projects_for_work_package_model.yml index d0c88ba784a..90da7be8297 100644 --- a/docs/api/apiv3/components/schemas/available_projects_for_work_package_model.yml +++ b/docs/api/apiv3/components/schemas/available_projects_for_work_package_model.yml @@ -16,7 +16,7 @@ example: href: "/api/v3/projects/6" title: A project editWorkPackage: - href: "/api/v3//work_packages/{work_package_id}/form" + href: "/api/v3/work_packages/{id}/form" templated: true method: post createWorkPackage: diff --git a/docs/api/apiv3/example/README.md b/docs/api/apiv3/example/README.md index c5d8ebdd737..e2b94a59e4d 100644 --- a/docs/api/apiv3/example/README.md +++ b/docs/api/apiv3/example/README.md @@ -147,7 +147,7 @@ A form: * contains a *schema* describing the properties of the work package as well as listing the available values for those referencing other resources. E.g. the projects in which work packages can be created (read in which the user has the permission to create work packages) are listed. * notes the current *errors* in the payload. E.g. a work package cannot be created outside of a project so a project reference needs to be provided. -The API documentation offers detailed information [on forms in general](../forms) and on the [work package create form](../endpoints/work-packages#work-packages-work-package-create-form) in particular. +The API documentation offers detailed information [on forms in general](../forms) and on the [work package create form](../endpoints/work-packages/#work-package-create-form-for-project) in particular. We will first fetch the empty form: @@ -226,7 +226,7 @@ The set of available custom fields might change depending on the values provided As some custom fields reference other resources (e.g. list and user) while others are scalar values (e.g. integer and float), setting the properties requires to have them set in different parts of the body payload. This is the same as for the `subject` property vs. the `project` property. The schema can instruct the client where to set them properly. All properties with an `availableValues` section either listing values themselves or linking to them need to be placed in the `_links` section of the payload. -``` +```json { # Scalar values "customFieldX": 123, diff --git a/docs/api/apiv3/openapi-spec.yml b/docs/api/apiv3/openapi-spec.yml index a9b59ef3627..618f49bf742 100644 --- a/docs/api/apiv3/openapi-spec.yml +++ b/docs/api/apiv3/openapi-spec.yml @@ -3,7 +3,7 @@ openapi: 3.0.0 info: description: |- You're looking at the current **stable** documentation of the OpenProject APIv3. If you're interested in the current - development version, please go to https://docs.openproject.org/api/ + development version, please go to [github.com/opf](https://github.com/opf/openproject/tree/dev/docs/api/apiv3). ## Introduction @@ -14,19 +14,19 @@ info: authenticated user can take are being rendered. This can be used to dynamically identify actions that the user might take for any given response. - As an example, if you fetch a work package through the [Work Package endpoint](#work-packages), the `update` link will only + As an example, if you fetch a work package through the [Work Package endpoint](https://www.openproject.org/docs/api/endpoints/work-packages/), the `update` link will only be present when the user you authenticated has been granted a permission to update the work package in the assigned project. ## HAL+JSON HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API. - Read more in the following specification: https://tools.ietf.org/html/draft-kelly-json-hal-08 + Read more in the following specification: [https://tools.ietf.org/html/draft-kelly-json-hal-08](https://tools.ietf.org/html/draft-kelly-json-hal-08) **OpenProject API implementation of HAL+JSON format** enriches JSON and introduces a few meta properties: - `_type` - specifies the type of the resource (e.g.: WorkPackage, Project) - - `_links` - contains all related resource and action links available for the resource - - `_embedded` - contains all embedded objects + - `_links` - contains all related resource and action links available for the resource + - `_embedded` - contains all embedded objects HAL does not guarantee that embedded resources are embedded in their full representation, they might as well be partially represented (e.g. some properties can be left out). @@ -36,9 +36,9 @@ info: All API responses contain a single HAL+JSON object, even collections of objects are technically represented by a single HAL+JSON object that itself contains its members. More details on collections can be found - in the [Collections Section](#collections). + in the [Collections Section](https://www.openproject.org/docs/api/group-objects/). - # Authentication + ## Authentication The API supports the following authentication schemes: OAuth2, session based authentication, and basic auth. @@ -48,14 +48,14 @@ info: Otherwise unauthenticated clients have all the permissions of the anonymous user. - ## Session-based Authentication + ### Session-based Authentication This means you have to login to OpenProject via the Web-Interface to be authenticated in the API. This method is well-suited for clients acting within the browser, like the Angular-Client built into OpenProject. In this case, you always need to pass the HTTP header `X-Requested-With "XMLHttpRequest"` for authentication. - ## API Key through Basic Auth + ### API Key through Basic Auth Users can authenticate towards the API v3 using basic auth with `apikey` (as a string, NOT your API key) as the user name and their API key as the password. Users can find their API key on their account page. @@ -67,7 +67,7 @@ info: curl -u apikey:$API_KEY https://community.openproject.com/api/v3/users/42 ``` - ## OAuth2.0 authentication + ### OAuth2.0 authentication OpenProject allows authentication and authorization with OAuth2 with *Authorization code flow*, as well as *Client credentials* operation modes. @@ -80,7 +80,7 @@ info: - [Client credentials](https://oauth.net/2/grant-types/client-credentials/) - Requires an application to be bound to an impersonating user for non-public access - ## Why not username and password? + ### Why not username and password? The simplest way to do basic auth would be to use a user's username and password naturally. However, OpenProject already has supported API keys in the past for the API v2, though not through basic auth. @@ -100,15 +100,15 @@ info: Most importantly users may not actually have a password to begin with. Specifically when they have registered through an OpenID Connect provider. - # Cross-Origin Resource Sharing (CORS) + ## Cross-Origin Resource Sharing (CORS) By default, the OpenProject API is _not_ responding with any CORS headers. If you want to allow cross-domain AJAX calls against your OpenProject instance, you need to enable CORS headers being returned. - Please see [our API settings documentation](https://docs.openproject.org/system-admin-guide/system-settings/api-settings/) on + Please see [our API settings documentation](https://www.openproject.org/docs/system-admin-guide/system-settings/api-settings/) on how to selectively enable CORS. - # Allowed HTTP methods + ## Allowed HTTP methods - `GET` - Get a single resource or collection of resources @@ -118,7 +118,7 @@ info: - `DELETE` - Delete a resource - # Compression + ## Compression Responses are compressed if requested by the client. Currently [gzip](http://www.gzip.org/) and [deflate](https://tools.ietf.org/html/rfc1951) are supported. The client signals the desired compression by setting the [`Accept-Encoding` header](https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.3). @@ -151,9 +151,9 @@ paths: "$ref": "./paths/category.yml" "/api/v3/configuration": "$ref": "./paths/configuration.yml" - "/api/v3/custom_actions/{custom_action_id}": + "/api/v3/custom_actions/{id}": "$ref": "./paths/custom_action.yml" - "/api/v3/custom_actions/{custom_action_id}/execute": + "/api/v3/custom_actions/{id}/execute": "$ref": "./paths/custom_action_execute.yml" "/api/v3/custom_objects/{id}": "$ref": "./paths/custom_object.yml" @@ -241,15 +241,15 @@ paths: "$ref": "./paths/project_work_packages.yml" "/api/v3/projects/{id}/work_packages/form": "$ref": "./paths/project_work_packages_form.yml" - "/api/v3/projects/{project_id}/available_assignees": + "/api/v3/projects/{id}/available_assignees": "$ref": "./paths/project_available_assignees.yml" - "/api/v3/projects/{project_id}/available_responsibles": + "/api/v3/projects/{id}/available_responsibles": "$ref": "./paths/project_available_responsibles.yml" - "/api/v3/projects/{project_id}/categories": + "/api/v3/projects/{id}/categories": "$ref": "./paths/project_categories.yml" - "/api/v3/projects/{project_id}/types": + "/api/v3/projects/{id}/types": "$ref": "./paths/project_types.yml" - "/api/v3/projects/{project_id}/versions": + "/api/v3/projects/{id}/versions": "$ref": "./paths/project_versions.yml" "/api/v3/queries": "$ref": "./paths/queries.yml" @@ -261,8 +261,8 @@ paths: "$ref": "./paths/queries_default.yml" "/api/v3/queries/filter_instance_schemas": "$ref": "./paths/queries_filter_instance_schemas.yml" - "/api/v3/queries/filter_instance_schemas/{identifier}": - "$ref": "./paths/queries_filter_instance_schemas_{identifier}.yml" + "/api/v3/queries/filter_instance_schemas/{id}": + "$ref": "./paths/queries_filter_instance_schemas_{id}.yml" "/api/v3/queries/filters/{id}": "$ref": "./paths/queries_filter.yml" "/api/v3/queries/form": @@ -305,8 +305,8 @@ paths: "$ref": "./paths/status.yml" "/api/v3/time_entries": "$ref": "./paths/time_entries.yml" - "/api/v3/time_entries/:id/form": - "$ref": "./paths/time_entries_:id_form.yml" + "/api/v3/time_entries/{id}/form": + "$ref": "./paths/time_entries_id_form.yml" "/api/v3/time_entries/activity/{id}": "$ref": "./paths/time_entries_activity_item.yml" "/api/v3/time_entries/available_projects": @@ -375,11 +375,11 @@ paths: "$ref": "./paths/work_package_relations_form.yml" "/api/v3/work_packages/{id}/revisions": "$ref": "./paths/work_package_revisions.yml" - "/api/v3/work_packages/{work_package_id}/relations": + "/api/v3/work_packages/{id}/relations": "$ref": "./paths/work_package_relations.yml" - "/api/v3/work_packages/{work_package_id}/watchers": + "/api/v3/work_packages/{id}/watchers": "$ref": "./paths/work_package_watchers.yml" - "/api/v3/work_packages/{work_package_id}/watchers/{id}": + "/api/v3/work_packages/{id}/watchers/{user_id}": "$ref": "./paths/work_package_watcher.yml" components: schemas: diff --git a/docs/api/apiv3/paths/actions.yml b/docs/api/apiv3/paths/actions.yml index 13014e9242b..2b23eeedd5c 100644 --- a/docs/api/apiv3/paths/actions.yml +++ b/docs/api/apiv3/paths/actions.yml @@ -4,7 +4,7 @@ get: parameters: - description: |- JSON specifying filter conditions. - Accepts the same format as returned by the [queries](#queries) endpoint. + Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint. Currently supported filters are: + id: Returns only the action having the id or all actions except those having the id(s). @@ -16,7 +16,7 @@ get: type: string - description: |- JSON specifying sort criteria. - Accepts the same format as returned by the [queries](#queries) endpoint. Currently supported sorts are: + Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint. Currently supported sorts are: + *No sort supported yet* example: '[["id", "asc"]]' @@ -24,7 +24,7 @@ get: name: sortBy required: false schema: - default: '["id", "asc"]' + default: '[["id", "asc"]]' type: string responses: '200': diff --git a/docs/api/apiv3/paths/capabilities.yml b/docs/api/apiv3/paths/capabilities.yml index 2026d883110..b91fab8f439 100644 --- a/docs/api/apiv3/paths/capabilities.yml +++ b/docs/api/apiv3/paths/capabilities.yml @@ -4,7 +4,7 @@ get: parameters: - description: |- JSON specifying filter conditions. - Accepts the same format as returned by the [queries](#queries) endpoint. + Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint. + action: Get all capabilities of a certain action @@ -19,7 +19,7 @@ get: type: string - description: |- JSON specifying sort criteria. - Accepts the same format as returned by the [queries](#queries) endpoint. Currently supported sorts are: + Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint. Currently supported sorts are: + id: Sort by the capabilities id example: '[["id", "asc"]]' @@ -27,7 +27,7 @@ get: name: sortBy required: false schema: - default: '["id", "asc"]' + default: '[["id", "asc"]]' type: string responses: '200': diff --git a/docs/api/apiv3/paths/category.yml b/docs/api/apiv3/paths/category.yml index a5e17d22f7b..c8007e6ae60 100644 --- a/docs/api/apiv3/paths/category.yml +++ b/docs/api/apiv3/paths/category.yml @@ -2,7 +2,7 @@ --- get: parameters: - - description: category id + - description: Category id example: '1' in: path name: id diff --git a/docs/api/apiv3/paths/custom_action.yml b/docs/api/apiv3/paths/custom_action.yml index 24b1068def9..7c51c2de13a 100644 --- a/docs/api/apiv3/paths/custom_action.yml +++ b/docs/api/apiv3/paths/custom_action.yml @@ -1,11 +1,11 @@ -# /api/v3/custom_actions/{custom_action_id} +# /api/v3/custom_actions/{id} --- get: parameters: - description: The id of the custom action to fetch example: '1' in: path - name: custom_action_id + name: id required: true schema: type: integer diff --git a/docs/api/apiv3/paths/custom_action_execute.yml b/docs/api/apiv3/paths/custom_action_execute.yml index 5b59ddcbc78..ec87f527a64 100644 --- a/docs/api/apiv3/paths/custom_action_execute.yml +++ b/docs/api/apiv3/paths/custom_action_execute.yml @@ -1,11 +1,11 @@ -# /api/v3/custom_actions/{custom_action_id}/execute +# /api/v3/custom_actions/{id}/execute --- post: parameters: - description: The id of the custom action to execute example: '1' in: path - name: custom_action_id + name: id required: true schema: type: integer diff --git a/docs/api/apiv3/paths/document.yml b/docs/api/apiv3/paths/document.yml index e7f9c512b38..c3231cc16d7 100644 --- a/docs/api/apiv3/paths/document.yml +++ b/docs/api/apiv3/paths/document.yml @@ -2,7 +2,7 @@ --- get: parameters: - - description: document id + - description: Document id example: '1' in: path name: id diff --git a/docs/api/apiv3/paths/documents.yml b/docs/api/apiv3/paths/documents.yml index 28cab844597..6e888a68282 100644 --- a/docs/api/apiv3/paths/documents.yml +++ b/docs/api/apiv3/paths/documents.yml @@ -19,7 +19,7 @@ get: type: integer - description: |- JSON specifying sort criteria. - Accepts the same format as returned by the [queries](#queries) endpoint. Currently supported sorts are: + Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint. Currently supported sorts are: + id: Sort by primary key diff --git a/docs/api/apiv3/paths/examples.yml b/docs/api/apiv3/paths/examples.yml index ae736bc5c60..ae67a9218bc 100644 --- a/docs/api/apiv3/paths/examples.yml +++ b/docs/api/apiv3/paths/examples.yml @@ -5,7 +5,7 @@ get: - description: |- The column to group by. Note: Aggregation is as of now only supported by the work package collection. - You can pass any column name as returned by the [queries](#queries) endpoint. + You can pass any column name as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint. example: status in: query name: groupBy @@ -13,6 +13,7 @@ get: schema: type: string - description: '' + example: 'true' in: query name: showSums required: false diff --git a/docs/api/apiv3/paths/grid.yml b/docs/api/apiv3/paths/grid.yml index 40c33e8a1ad..2b3fe7d9555 100644 --- a/docs/api/apiv3/paths/grid.yml +++ b/docs/api/apiv3/paths/grid.yml @@ -2,7 +2,7 @@ --- get: parameters: - - description: grid id + - description: Grid id example: '1' in: path name: id diff --git a/docs/api/apiv3/paths/grids.yml b/docs/api/apiv3/paths/grids.yml index 1ef99867929..be28a3ce1c7 100644 --- a/docs/api/apiv3/paths/grids.yml +++ b/docs/api/apiv3/paths/grids.yml @@ -19,7 +19,7 @@ get: type: integer - description: |- JSON specifying filter conditions. - Accepts the same format as returned by the [queries](#queries) endpoint. Currently supported filters are: + Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint. Currently supported filters are: + page: Filter grid by work package example: '[{ "page": { "operator": "=", "values": ["/my/page"] } }]' diff --git a/docs/api/apiv3/paths/group.yml b/docs/api/apiv3/paths/group.yml index 0363c6ae804..8d575754d16 100644 --- a/docs/api/apiv3/paths/group.yml +++ b/docs/api/apiv3/paths/group.yml @@ -56,7 +56,7 @@ delete: summary: Delete group get: parameters: - - description: Group id. + - description: Group id example: '1' in: path name: id @@ -130,6 +130,32 @@ patch: '200': content: application/hal+json: + examples: + response: + value: + _links: + delete: + href: "/api/v3/group/9" + method: delete + members: + - href: "/api/v3/users/363" + title: First user + - href: "/api/v3/users/60" + title: Second user + memberships: + href: /api/v3/memberships?filters=[{"principal":{"operator":"=","values":["9"]}}] + title: Memberships + self: + href: "/api/v3/groups/9" + title: The group + updateImmediately: + href: "/api/v3/group/9" + method: patch + _type: Group + createdAt: '2015-09-23T11:06:36Z' + id: 9 + name: The group + updatedAt: '2015-09-23T11:06:36Z' schema: "$ref": "../components/schemas/view_group_model.yml" description: OK diff --git a/docs/api/apiv3/paths/groups.yml b/docs/api/apiv3/paths/groups.yml index 4ae3124df9b..dddbbec5639 100644 --- a/docs/api/apiv3/paths/groups.yml +++ b/docs/api/apiv3/paths/groups.yml @@ -4,7 +4,7 @@ get: parameters: - description: |- JSON specifying sort criteria. - Accepts the same format as returned by the [queries](#queries) endpoint. Currently supported sorts are: + Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint. Currently supported sorts are: + id: Sort by primary key @@ -16,7 +16,7 @@ get: name: sortBy required: false schema: - default: '["id", "asc"]' + default: '[["id", "asc"]]' type: string responses: '200': diff --git a/docs/api/apiv3/paths/membership.yml b/docs/api/apiv3/paths/membership.yml index 118dfcd292a..a6f8a97f490 100644 --- a/docs/api/apiv3/paths/membership.yml +++ b/docs/api/apiv3/paths/membership.yml @@ -52,7 +52,7 @@ delete: summary: Delete membership get: parameters: - - description: membership id + - description: Membership id example: '1' in: path name: id diff --git a/docs/api/apiv3/paths/memberships.yml b/docs/api/apiv3/paths/memberships.yml index ae1a04228e0..4415b78c578 100644 --- a/docs/api/apiv3/paths/memberships.yml +++ b/docs/api/apiv3/paths/memberships.yml @@ -4,7 +4,7 @@ get: parameters: - description: |- JSON specifying filter conditions. - Accepts the same format as returned by the [queries](#queries) endpoint. + Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint. Currently supported filters are: + any_name_attribute: filters memberships based on the name of the principal. All possible name variants (and also email and login) are searched. @@ -34,7 +34,7 @@ get: type: string - description: |- JSON specifying sort criteria. - Accepts the same format as returned by the [queries](#queries) endpoint. Currently supported sorts are: + Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint. Currently supported sorts are: + id: Sort by primary key @@ -52,7 +52,7 @@ get: name: sortBy required: false schema: - default: '["id", "asc"]' + default: '[["id", "asc"]]' type: string responses: '200': diff --git a/docs/api/apiv3/paths/memberships_available_projects.yml b/docs/api/apiv3/paths/memberships_available_projects.yml index 03157dcff7f..a33552d0063 100644 --- a/docs/api/apiv3/paths/memberships_available_projects.yml +++ b/docs/api/apiv3/paths/memberships_available_projects.yml @@ -20,7 +20,7 @@ get: href: "/api/v3/projects/6/work_packages" method: post editWorkPackage: - href: "/api/v3//work_packages/{work_package_id}/form" + href: "/api/v3//work_packages/{id}/form" method: post templated: true memberships: diff --git a/docs/api/apiv3/paths/news.yml b/docs/api/apiv3/paths/news.yml index d05aa81a49f..eac8acc6080 100644 --- a/docs/api/apiv3/paths/news.yml +++ b/docs/api/apiv3/paths/news.yml @@ -19,7 +19,7 @@ get: type: integer - description: |- JSON specifying sort criteria. - Accepts the same format as returned by the [queries](#queries) endpoint. Currently supported sorts are: + Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint. Currently supported sorts are: + id: Sort by primary key @@ -32,7 +32,7 @@ get: type: string - description: |- JSON specifying filter conditions. - Accepts the same format as returned by the [queries](#queries) endpoint. Currently supported filters are: + Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint. Currently supported filters are: + project_id: Filter news by project example: '[{ "project_id": { "operator": "=", "values": ["1", "2"] } }]' diff --git a/docs/api/apiv3/paths/post_attachments.yml b/docs/api/apiv3/paths/post_attachments.yml index c62e0ba1cbe..e4c04b41b7e 100644 --- a/docs/api/apiv3/paths/post_attachments.yml +++ b/docs/api/apiv3/paths/post_attachments.yml @@ -242,6 +242,5 @@ post: description: |- Adds an attachment with the post as it's container. - See [the general specification for uploading attachments](#attachments-attachments) for details. operationId: Add_attachment_to_post summary: Add attachment to post diff --git a/docs/api/apiv3/paths/principals.yml b/docs/api/apiv3/paths/principals.yml index 1986e942bea..10ba8bc3ce5 100644 --- a/docs/api/apiv3/paths/principals.yml +++ b/docs/api/apiv3/paths/principals.yml @@ -4,7 +4,7 @@ get: parameters: - description: |- JSON specifying filter conditions. - Accepts the same format as returned by the [queries](#queries) endpoint. + Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint. Currently supported filters are: + type: filters principals by their type (*User*, *Group*, *PlaceholderUser*). diff --git a/docs/api/apiv3/paths/project_available_assignees.yml b/docs/api/apiv3/paths/project_available_assignees.yml index b458a653d88..2adc59b71fc 100644 --- a/docs/api/apiv3/paths/project_available_assignees.yml +++ b/docs/api/apiv3/paths/project_available_assignees.yml @@ -1,11 +1,11 @@ -# /api/v3/projects/{project_id}/available_assignees +# /api/v3/projects/{id}/available_assignees --- get: parameters: - description: Project id example: '1' in: path - name: project_id + name: id required: true schema: type: integer diff --git a/docs/api/apiv3/paths/project_available_responsibles.yml b/docs/api/apiv3/paths/project_available_responsibles.yml index 2d57711cad3..bb8fd84e67a 100644 --- a/docs/api/apiv3/paths/project_available_responsibles.yml +++ b/docs/api/apiv3/paths/project_available_responsibles.yml @@ -1,11 +1,11 @@ -# /api/v3/projects/{project_id}/available_responsibles +# /api/v3/projects/{id}/available_responsibles --- get: parameters: - description: Project id example: '1' in: path - name: project_id + name: id required: true schema: type: integer diff --git a/docs/api/apiv3/paths/project_categories.yml b/docs/api/apiv3/paths/project_categories.yml index 5cf8125d49e..c1e9df5473c 100644 --- a/docs/api/apiv3/paths/project_categories.yml +++ b/docs/api/apiv3/paths/project_categories.yml @@ -1,11 +1,11 @@ -# /api/v3/projects/{project_id}/categories +# /api/v3/projects/{id}/categories --- get: parameters: - description: ID of the project whose categories will be listed example: '1' in: path - name: project_id + name: id required: true schema: type: integer diff --git a/docs/api/apiv3/paths/project_queries_default.yml b/docs/api/apiv3/paths/project_queries_default.yml index 97af883747b..a665415fd0f 100644 --- a/docs/api/apiv3/paths/project_queries_default.yml +++ b/docs/api/apiv3/paths/project_queries_default.yml @@ -44,7 +44,7 @@ get: name: sortBy required: false schema: - default: '["id", "asc"]' + default: '[["id", "asc"]]' type: string - description: The column to group by. The grouping criteria is applied to the to the query's result collection of work packages overriding the query's persisted @@ -201,7 +201,7 @@ get: headers: {} tags: - Queries - description: Same as [viewing an existing, persisted Query](#queries-query-get) + description: Same as [viewing an existing, persisted Query](https://www.openproject.org/docs/api/endpoints/queries/#list-queries) in its response, this resource returns an unpersisted query and by that allows to get the default query configuration. The client may also provide additional parameters which will modify the default query. The query will already be scoped diff --git a/docs/api/apiv3/paths/project_queries_filter_instance_schemas.yml b/docs/api/apiv3/paths/project_queries_filter_instance_schemas.yml index a802ff74a4f..da899830be2 100644 --- a/docs/api/apiv3/paths/project_queries_filter_instance_schemas.yml +++ b/docs/api/apiv3/paths/project_queries_filter_instance_schemas.yml @@ -2,7 +2,7 @@ --- get: parameters: - - description: Id of the project. + - description: Project id example: '1' in: path name: id diff --git a/docs/api/apiv3/paths/project_types.yml b/docs/api/apiv3/paths/project_types.yml index dbdce991258..52896b6e12b 100644 --- a/docs/api/apiv3/paths/project_types.yml +++ b/docs/api/apiv3/paths/project_types.yml @@ -1,11 +1,11 @@ -# /api/v3/projects/{project_id}/types +# /api/v3/projects/{id}/types --- get: parameters: - description: ID of the project whose types will be listed example: '1' in: path - name: project_id + name: id required: true schema: type: integer diff --git a/docs/api/apiv3/paths/project_versions.yml b/docs/api/apiv3/paths/project_versions.yml index d9b645674d2..d2588b1bd97 100644 --- a/docs/api/apiv3/paths/project_versions.yml +++ b/docs/api/apiv3/paths/project_versions.yml @@ -1,11 +1,11 @@ -# /api/v3/projects/{project_id}/versions +# /api/v3/projects/{id}/versions --- get: parameters: - description: ID of the project whose versions will be listed example: '1' in: path - name: project_id + name: id required: true schema: type: integer diff --git a/docs/api/apiv3/paths/project_work_packages.yml b/docs/api/apiv3/paths/project_work_packages.yml index 04e679de22c..ab4f9c7ad25 100644 --- a/docs/api/apiv3/paths/project_work_packages.yml +++ b/docs/api/apiv3/paths/project_work_packages.yml @@ -26,7 +26,7 @@ get: type: integer - description: |- JSON specifying filter conditions. - Accepts the same format as returned by the [queries](#queries) endpoint. If no filter is to be applied, the client should send an empty array (`[]`). + Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint. If no filter is to be applied, the client should send an empty array (`[]`). example: '[{ "type_id": { "operator": "=", "values": [''1'', ''2''] }}]' in: query name: filters @@ -36,13 +36,13 @@ get: type: string - description: |- JSON specifying sort criteria. - Accepts the same format as returned by the [queries](#queries) endpoint. + Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint. example: '[["status", "asc"]]' in: query name: sortBy required: false schema: - default: '["id", "asc"]' + default: '[["id", "asc"]]' type: string - description: The column to group by. example: status diff --git a/docs/api/apiv3/paths/projects.yml b/docs/api/apiv3/paths/projects.yml index 061d06563e4..25c2e96cf18 100644 --- a/docs/api/apiv3/paths/projects.yml +++ b/docs/api/apiv3/paths/projects.yml @@ -4,7 +4,7 @@ get: parameters: - description: |- JSON specifying filter conditions. - Accepts the same format as returned by the [queries](#queries) endpoint. + 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 project @@ -23,7 +23,7 @@ get: + type_id: based on the types active in a project. - + user_action: based on the actions (see [Actions](#actions)) the current user has in the project. + + user_action: based on the actions the current user has in the project. + id: based on projects' id. diff --git a/docs/api/apiv3/paths/projects_available_parent_projects.yml b/docs/api/apiv3/paths/projects_available_parent_projects.yml index f0d7f262fcf..89cc4bc62b0 100644 --- a/docs/api/apiv3/paths/projects_available_parent_projects.yml +++ b/docs/api/apiv3/paths/projects_available_parent_projects.yml @@ -19,7 +19,7 @@ get: type: string - description: |- JSON specifying sort criteria. - Accepts the same format as returned by the [queries](#queries) endpoint and allows all the filters and sortBy supported by the project list end point. + Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint and allows all the filters and sortBy supported by the project list end point. example: '[["id", "asc"]]' in: query name: sortBy diff --git a/docs/api/apiv3/paths/queries.yml b/docs/api/apiv3/paths/queries.yml index a51a7bc83ef..2ea35a87ccd 100644 --- a/docs/api/apiv3/paths/queries.yml +++ b/docs/api/apiv3/paths/queries.yml @@ -4,7 +4,6 @@ get: parameters: - description: |- 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. diff --git a/docs/api/apiv3/paths/queries_default.yml b/docs/api/apiv3/paths/queries_default.yml index 2d5617b7646..f65b36996f1 100644 --- a/docs/api/apiv3/paths/queries_default.yml +++ b/docs/api/apiv3/paths/queries_default.yml @@ -37,7 +37,7 @@ get: name: sortBy required: false schema: - default: '["id", "asc"]' + default: '[["id", "asc"]]' type: string - description: The column to group by. The grouping criteria is applied to the to the query's result collection of work packages overriding the query's persisted @@ -192,7 +192,7 @@ get: headers: {} tags: - Queries - description: Same as [viewing an existing, persisted Query](#queries-query-get) + description: Same as [viewing an existing, persisted Query](https://www.openproject.org/docs/api/endpoints/queries/#list-queries) in its response, this resource returns an unpersisted query and by that allows to get the default query configuration. The client may also provide additional parameters which will modify the default query. diff --git a/docs/api/apiv3/paths/queries_filter.yml b/docs/api/apiv3/paths/queries_filter.yml index 2e890708668..1c9be16e6e8 100644 --- a/docs/api/apiv3/paths/queries_filter.yml +++ b/docs/api/apiv3/paths/queries_filter.yml @@ -2,7 +2,7 @@ --- get: parameters: - - description: QueryFilter identifier. + - description: QueryFilter identifier example: status in: path name: id diff --git a/docs/api/apiv3/paths/queries_filter_instance_schemas_{identifier}.yml b/docs/api/apiv3/paths/queries_filter_instance_schemas_{id}.yml similarity index 97% rename from docs/api/apiv3/paths/queries_filter_instance_schemas_{identifier}.yml rename to docs/api/apiv3/paths/queries_filter_instance_schemas_{id}.yml index 5223366a6d8..fb92ab60395 100644 --- a/docs/api/apiv3/paths/queries_filter_instance_schemas_{identifier}.yml +++ b/docs/api/apiv3/paths/queries_filter_instance_schemas_{id}.yml @@ -1,4 +1,4 @@ -# /api/v3/queries/filter_instance_schemas/{identifier} +# /api/v3/queries/filter_instance_schemas/{id} --- get: parameters: @@ -6,7 +6,7 @@ get: identifier. example: author in: path - name: identifier + name: id required: true schema: type: string diff --git a/docs/api/apiv3/paths/query.yml b/docs/api/apiv3/paths/query.yml index 6f2b75eba5b..92c51678fe4 100644 --- a/docs/api/apiv3/paths/query.yml +++ b/docs/api/apiv3/paths/query.yml @@ -102,7 +102,7 @@ get: name: sortBy required: false schema: - default: '["id", "asc"]' + default: '[["id", "asc"]]' type: string - description: The column to group by. The grouping criteria is applied to the to the query's result collection of work packages overriding the query's persisted diff --git a/docs/api/apiv3/paths/relations.yml b/docs/api/apiv3/paths/relations.yml index 69496b6bbf9..c03abba9228 100644 --- a/docs/api/apiv3/paths/relations.yml +++ b/docs/api/apiv3/paths/relations.yml @@ -4,7 +4,7 @@ get: parameters: - description: |- JSON specifying filter conditions. - Accepts the same format as returned by the [queries](#queries) endpoint. Valid fields to filter by are: + Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint. Valid fields to filter by are: + id - ID of relation @@ -23,7 +23,7 @@ get: type: string - description: |- JSON specifying sort criteria. - Accepts the same format as returned by the [queries](#queries) endpoint. + Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint. example: '[["type", "asc"]]' in: query name: sortBy diff --git a/docs/api/apiv3/paths/render_markdown.yml b/docs/api/apiv3/paths/render_markdown.yml index f6d4dd95236..b4abcfa3edd 100644 --- a/docs/api/apiv3/paths/render_markdown.yml +++ b/docs/api/apiv3/paths/render_markdown.yml @@ -21,16 +21,10 @@ post: responses: '200': content: - application/json: - schema: - "$ref": "../components/schemas/markdown_model.yml" text/html: examples: response: - value: '

Hello world! This is - markdown!

- -' + value: '

Hello world! This is markdown!

' schema: "$ref": "../components/schemas/markdown_model.yml" description: OK diff --git a/docs/api/apiv3/paths/render_plain.yml b/docs/api/apiv3/paths/render_plain.yml index f356cc46f4a..cf5675a85e7 100644 --- a/docs/api/apiv3/paths/render_plain.yml +++ b/docs/api/apiv3/paths/render_plain.yml @@ -4,9 +4,6 @@ post: responses: '200': content: - application/json: - schema: - "$ref": "../components/schemas/plain_text_model.yml" text/html: examples: response: diff --git a/docs/api/apiv3/paths/role.yml b/docs/api/apiv3/paths/role.yml index f17cfea15c1..83b5ea9ed31 100644 --- a/docs/api/apiv3/paths/role.yml +++ b/docs/api/apiv3/paths/role.yml @@ -2,7 +2,7 @@ --- get: parameters: - - description: role id + - description: Role id example: '1' in: path name: id diff --git a/docs/api/apiv3/paths/roles.yml b/docs/api/apiv3/paths/roles.yml index f4b40eb3b8e..8b77ab4fb0b 100644 --- a/docs/api/apiv3/paths/roles.yml +++ b/docs/api/apiv3/paths/roles.yml @@ -4,7 +4,7 @@ get: parameters: - description: |- JSON specifying filter conditions. - Accepts the same format as returned by the [queries](#queries) endpoint. + Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint. Currently supported filters are: + grantable: filters roles based on whether they are selectable for a membership diff --git a/docs/api/apiv3/paths/status.yml b/docs/api/apiv3/paths/status.yml index b0def93bea4..507e51019fb 100644 --- a/docs/api/apiv3/paths/status.yml +++ b/docs/api/apiv3/paths/status.yml @@ -2,7 +2,7 @@ --- get: parameters: - - description: status id + - description: Status id example: '1' in: path name: id diff --git a/docs/api/apiv3/paths/time_entries.yml b/docs/api/apiv3/paths/time_entries.yml index b0b5c8c66aa..592a314668e 100644 --- a/docs/api/apiv3/paths/time_entries.yml +++ b/docs/api/apiv3/paths/time_entries.yml @@ -19,7 +19,7 @@ get: type: integer - description: |- JSON specifying sort criteria. - Accepts the same format as returned by the [queries](#queries) endpoint. Currently supported sorts are: + Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint. Currently supported sorts are: + id: Sort by primary key @@ -39,7 +39,7 @@ get: type: string - description: |- JSON specifying filter conditions. - Accepts the same format as returned by the [queries](#queries) endpoint. Currently supported filters are: + Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint. Currently supported filters are: + work_package: Filter time entries by work package diff --git a/docs/api/apiv3/paths/time_entries_activity_item.yml b/docs/api/apiv3/paths/time_entries_activity_item.yml index 9c13208bad3..b45593fcf3d 100644 --- a/docs/api/apiv3/paths/time_entries_activity_item.yml +++ b/docs/api/apiv3/paths/time_entries_activity_item.yml @@ -2,7 +2,7 @@ --- get: parameters: - - description: time entries activity id + - description: Time entries activity id example: '1' in: path name: id diff --git a/docs/api/apiv3/paths/time_entries_:id_form.yml b/docs/api/apiv3/paths/time_entries_id_form.yml similarity index 89% rename from docs/api/apiv3/paths/time_entries_:id_form.yml rename to docs/api/apiv3/paths/time_entries_id_form.yml index 4cd492d1b03..d64ffd523ad 100644 --- a/docs/api/apiv3/paths/time_entries_:id_form.yml +++ b/docs/api/apiv3/paths/time_entries_id_form.yml @@ -1,6 +1,14 @@ -# /api/v3/time_entries/:id/form +# /api/v3/time_entries/{id}/form --- post: + parameters: + - description: Time entries activity id + example: '1' + in: path + name: id + required: true + schema: + type: integer responses: '200': description: OK @@ -54,6 +62,6 @@ post: application/json: schema: type: integer - description: time entries activity id + description: Time entries activity id required: true summary: Time entry update form diff --git a/docs/api/apiv3/paths/type.yml b/docs/api/apiv3/paths/type.yml index 10e65b3eb2f..01f07b102a0 100644 --- a/docs/api/apiv3/paths/type.yml +++ b/docs/api/apiv3/paths/type.yml @@ -2,7 +2,7 @@ --- get: parameters: - - description: type id + - description: Type id example: '1' in: path name: id diff --git a/docs/api/apiv3/paths/users.yml b/docs/api/apiv3/paths/users.yml index 5fafdb178b7..49832dbdc05 100644 --- a/docs/api/apiv3/paths/users.yml +++ b/docs/api/apiv3/paths/users.yml @@ -19,7 +19,7 @@ get: type: integer - description: |- JSON specifying filter conditions. - Accepts the same format as returned by the [queries](#queries) endpoint. Currently supported filters are: + Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint. Currently supported filters are: + status: Status the user has @@ -38,7 +38,7 @@ get: type: string - description: |- JSON specifying sort criteria. - Accepts the same format as returned by the [queries](#queries) endpoint. + Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint. example: '[["status", "asc"]]' in: query name: sortBy @@ -187,7 +187,9 @@ post: Valid values for `status`: 1) "active" - In this case a password has to be provided in addition to the other attributes. + 2) "invited" - In this case nothing but the email address is required. The rest is optional. An invitation will be sent to the user. + operationId: Create_User requestBody: content: diff --git a/docs/api/apiv3/paths/version.yml b/docs/api/apiv3/paths/version.yml index cc4f86924a1..a1fb90a256c 100644 --- a/docs/api/apiv3/paths/version.yml +++ b/docs/api/apiv3/paths/version.yml @@ -53,7 +53,7 @@ delete: summary: Delete Version get: parameters: - - description: version id + - description: Version id example: '1' in: path name: id diff --git a/docs/api/apiv3/paths/versions.yml b/docs/api/apiv3/paths/versions.yml index c3ada0ac17c..07e5b477955 100644 --- a/docs/api/apiv3/paths/versions.yml +++ b/docs/api/apiv3/paths/versions.yml @@ -4,7 +4,7 @@ get: parameters: - description: |- JSON specifying filter conditions. - Accepts the same format as returned by the [queries](#queries) endpoint. + Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint. Currently supported filters are: + sharing: filters versions by how they are shared within the server (*none*, *descendants*, *hierarchy*, *tree*, *system*). diff --git a/docs/api/apiv3/paths/versions_available_projects.yml b/docs/api/apiv3/paths/versions_available_projects.yml index 565f76bfe54..ea8782bd81e 100644 --- a/docs/api/apiv3/paths/versions_available_projects.yml +++ b/docs/api/apiv3/paths/versions_available_projects.yml @@ -20,7 +20,7 @@ get: href: "/api/v3/projects/6/work_packages" method: post editWorkPackage: - href: "/api/v3//work_packages/{work_package_id}/form" + href: "/api/v3//work_packages/{id}/form" method: post templated: true self: diff --git a/docs/api/apiv3/paths/wiki_page_attachments.yml b/docs/api/apiv3/paths/wiki_page_attachments.yml index df727ba036f..138a58c9f8f 100644 --- a/docs/api/apiv3/paths/wiki_page_attachments.yml +++ b/docs/api/apiv3/paths/wiki_page_attachments.yml @@ -242,6 +242,5 @@ post: description: |- Adds an attachment with the wiki page as it's container. - See [the general specification for uploading attachments](#attachments-attachments) for details. operationId: Add_attachment_to_wiki_page summary: Add attachment to wiki page diff --git a/docs/api/apiv3/paths/work_package_available_projects.yml b/docs/api/apiv3/paths/work_package_available_projects.yml index 4bc57f8b3e7..553f63f57fc 100644 --- a/docs/api/apiv3/paths/work_package_available_projects.yml +++ b/docs/api/apiv3/paths/work_package_available_projects.yml @@ -28,7 +28,7 @@ get: href: "/api/v3/projects/6/work_packages" method: post editWorkPackage: - href: "/api/v3//work_packages/{work_package_id}/form" + href: "/api/v3//work_packages/{id}/form" method: post templated: true self: diff --git a/docs/api/apiv3/paths/work_package_available_relation_candidates.yml b/docs/api/apiv3/paths/work_package_available_relation_candidates.yml index df1b8f3e3e4..9025e7ecd8c 100644 --- a/docs/api/apiv3/paths/work_package_available_relation_candidates.yml +++ b/docs/api/apiv3/paths/work_package_available_relation_candidates.yml @@ -18,7 +18,7 @@ get: type: integer - description: |- JSON specifying filter conditions. - Accepts the same format as returned by the [queries](#queries) endpoint. + Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint. example: '[{ "status_id": { "operator": "o", "values": null } }]' in: query name: filters diff --git a/docs/api/apiv3/paths/work_package_relations.yml b/docs/api/apiv3/paths/work_package_relations.yml index dc09aa36970..4d0e431ecdf 100644 --- a/docs/api/apiv3/paths/work_package_relations.yml +++ b/docs/api/apiv3/paths/work_package_relations.yml @@ -1,11 +1,11 @@ -# /api/v3/work_packages/{work_package_id}/relations +# /api/v3/work_packages/{id}/relations --- get: parameters: - description: Work package id example: '1' in: path - name: work_package_id + name: id required: true schema: type: integer @@ -15,9 +15,7 @@ get: text/plain: examples: response: - value: 'You are being redirected to /api/v3/relations?involved={work_package_id} - -' + value: 'You are being redirected to /api/v3/relations?involved={work_package_id}' description: Found headers: Location: @@ -33,7 +31,7 @@ post: - description: Work package id example: '1' in: path - name: work_package_id + name: id required: true schema: type: integer diff --git a/docs/api/apiv3/paths/work_package_revisions.yml b/docs/api/apiv3/paths/work_package_revisions.yml index c07f27a7d9e..82f85232fa1 100644 --- a/docs/api/apiv3/paths/work_package_revisions.yml +++ b/docs/api/apiv3/paths/work_package_revisions.yml @@ -2,7 +2,7 @@ --- get: parameters: - - description: work package id + - description: Work package id example: '1' in: path name: id diff --git a/docs/api/apiv3/paths/work_package_watcher.yml b/docs/api/apiv3/paths/work_package_watcher.yml index 63baa258d12..483c43021f4 100644 --- a/docs/api/apiv3/paths/work_package_watcher.yml +++ b/docs/api/apiv3/paths/work_package_watcher.yml @@ -1,18 +1,18 @@ -# /api/v3/work_packages/{work_package_id}/watchers/{id} +# /api/v3/work_packages/{id}/watchers/{user_id} --- delete: parameters: - description: Work package id example: '1' in: path - name: work_package_id + name: id required: true schema: type: integer - description: User id example: '1' in: path - name: id + name: user_id required: true schema: type: integer diff --git a/docs/api/apiv3/paths/work_package_watchers.yml b/docs/api/apiv3/paths/work_package_watchers.yml index c1f2a99928c..615bb1451d5 100644 --- a/docs/api/apiv3/paths/work_package_watchers.yml +++ b/docs/api/apiv3/paths/work_package_watchers.yml @@ -1,11 +1,11 @@ -# /api/v3/work_packages/{work_package_id}/watchers +# /api/v3/work_packages/{id}/watchers --- get: parameters: - description: Work package id example: '1' in: path - name: work_package_id + name: id required: true schema: type: integer @@ -117,7 +117,7 @@ post: - description: Work package id example: '1' in: path - name: work_package_id + name: id required: true schema: type: integer diff --git a/docs/api/apiv3/paths/work_packages.yml b/docs/api/apiv3/paths/work_packages.yml index cd6355df67f..88faf11125e 100644 --- a/docs/api/apiv3/paths/work_packages.yml +++ b/docs/api/apiv3/paths/work_packages.yml @@ -19,7 +19,7 @@ get: type: integer - description: |- JSON specifying filter conditions. - Accepts the same format as returned by the [queries](#queries) endpoint. If no filter is to be applied, the client should send an empty array (`[]`). + Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint. If no filter is to be applied, the client should send an empty array (`[]`). example: '[{ "type_id": { "operator": "=", "values": [''1'', ''2''] }}]' in: query name: filters @@ -29,13 +29,13 @@ get: type: string - description: |- JSON specifying sort criteria. - Accepts the same format as returned by the [queries](#queries) endpoint. + Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint. example: '[["status", "asc"]]' in: query name: sortBy required: false schema: - default: '["id", "asc"]' + default: '[["id", "asc"]]' type: string - description: The column to group by. example: status diff --git a/docs/api/apiv3/paths/work_packages_schemas.yml b/docs/api/apiv3/paths/work_packages_schemas.yml index 604c6f02361..3ceeeef8db7 100644 --- a/docs/api/apiv3/paths/work_packages_schemas.yml +++ b/docs/api/apiv3/paths/work_packages_schemas.yml @@ -4,7 +4,7 @@ get: parameters: - description: |- JSON specifying filter conditions. - Accepts the same format as returned by the [queries](#queries) endpoint. Currently supported filters are: + Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint. Currently supported filters are: + id: The schema's id example: '[{ "id": { "operator": "=", "values": ["12-1", "14-2"] } }]' diff --git a/docs/api/apiv3/tags/actions_and_capabilities.yml b/docs/api/apiv3/tags/actions_and_capabilities.yml index 2e4c5ebfa14..d6e45e69b18 100644 --- a/docs/api/apiv3/tags/actions_and_capabilities.yml +++ b/docs/api/apiv3/tags/actions_and_capabilities.yml @@ -18,7 +18,7 @@ description: |- Even though user might have a capability, it might still not be possible to carry out the action because some other requirement is not met. - E.g. A user might have the capability to update work packages, but if a particular work package is + E.g. a user might have the capability to update work packages, but if a particular work package is in a readonly state, that work package cannot be updated. *Only a small set of actions that actually already exist in the system are currently exposed via diff --git a/docs/api/apiv3/tags/activities.yml b/docs/api/apiv3/tags/activities.yml index f20b1708b96..2b4a0a31751 100644 --- a/docs/api/apiv3/tags/activities.yml +++ b/docs/api/apiv3/tags/activities.yml @@ -10,5 +10,5 @@ description: |- | details | | Array of Formattable | | 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`. name: Activities diff --git a/docs/api/apiv3/tags/basic_objects.yml b/docs/api/apiv3/tags/basic_objects.yml index 1af5e154bda..bd7ab3661d0 100644 --- a/docs/api/apiv3/tags/basic_objects.yml +++ b/docs/api/apiv3/tags/basic_objects.yml @@ -1,10 +1,10 @@ --- description: |- - # Links + ## Links Links to other resources in the API are represented uniformly by so called link objects. - ## Local Properties + ### Local Properties | Property | Description | Type | Required | Nullable | Default | |:---------:| ------------------------------------------------------------------------ | ------- |:--------:|:--------:| ----------- | @@ -16,13 +16,8 @@ description: |- | identifier| An optional unique identifier to the link object | String | | | unspecified | All link objects *must* contain the `href` property, though it might be `null`. Thus the following is a valid - link object: - - { - "href": null - } - - whereas `{ }` is not a valid link object. The meaning of `"href": null` is that **no** resource is referenced. + link object: `{ "href": null }` whereas `{ }` is not a valid link object. + The meaning of `"href": null` is that **no** resource is referenced. For example a work package without an assignee will still have an assignee link, but its `href` will be `null`. If a `title` is present, the client can display the title to the user when referring to the resource. @@ -50,13 +45,13 @@ description: |- original value. This is especially beneficial if the client creates and updates resources based on the payload object provided as part of a form as is recommended when interacting with the API. - # Errors + ## Errors In case of an error, the API will respond with an appropriate HTTP status code. For responses with an HTTP status of `4xx` and `5xx` the body will always contain a single error object. Error objects shall give the client additional details about the cause of an erroneous response. - ## General errors + ### General errors * Error objects have their `_type` set to `Error` @@ -71,38 +66,42 @@ description: |- * It *must not* include HTML or other kind of markup * Error messages form complete sentences including punctuation - ### Example + ##### Example + ```json { - "_type": "Error", - "errorIdentifier": "urn:openproject-org:api:v3:errors:InternalServerError", - "message": "An internal server error occurred. This is not your fault." - } + "_type": "Error", + "errorIdentifier": "urn:openproject-org:api:v3:errors:InternalServerError", + "message": "An internal server error occurred. This is not your fault." + } + ``` - ## Embedded error information + ### Embedded error information Errors might optionally contain embedded objects that contain further information. - ### Error details + #### Error details Under the embedded key `details` there might be an object describing the error more verbosely. For example if the error affects a specific field, this field could be defined there. - #### Example + ##### Example + ```json { - "_type": "Error", - "errorIdentifier": "urn:openproject-org:api:v3:examples:ExampleError", - "message": "This is an example error.", - "_embedded": { - "details": { - "_type": "ExampleErrorDetailInformation", - "erroneousField": "subject" - } - } + "_type": "Error", + "errorIdentifier": "urn:openproject-org:api:v3:examples:ExampleError", + "message": "This is an example error.", + "_embedded": { + "details": { + "_type": "ExampleErrorDetailInformation", + "erroneousField": "subject" } + } + } + ``` - ### Multiple error objects + #### Multiple error objects To ease implementation of basic clients it is guaranteed that the response body always only contains a single error object. However it is allowed that an error object *embeds* other error objects under the key `errors`, thereby aggregating them. @@ -110,63 +109,81 @@ description: |- The `errorIdentifier` of such an object is always `urn:openproject-org:api:v3:errors:MultipleErrors`. The message can either describe one of the embedded errors or simply state that multiple errors occurred. - #### Example + ##### Example + ```json { + "_type": "Error", + "errorIdentifier": "urn:openproject-org:api:v3:errors:MultipleErrors", + "message": "Multiple fields violated their constraints.", + "_embedded": { + "errors": [ + { "_type": "Error", - "errorIdentifier": "urn:openproject-org:api:v3:errors:MultipleErrors", - "message": "Multiple fields violated their constraints.", - "_embedded": { - "errors": [ - { - "_type": "Error", - "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation", - "...": "..." - }, - { - "_type": "Error", - "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation", - "...": "..." - } - ] - } - } + "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation", + "...": "..." + }, + { + "_type": "Error", + "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation", + "...": "..." + } + ] + } + } + ``` - ## List of Error Identifiers + ### List of Error Identifiers - * `urn:openproject-org:api:v3:errors:InvalidQuery` (**HTTP 400**) - The query contained a value that did not match the servers expectation + * `urn:openproject-org:api:v3:errors:InvalidQuery` (**HTTP 400**) + The query contained a value that did not match the servers expectation - * `urn:openproject-org:api:v3:errors:InvalidRequestBody` (**HTTP 400**) - The format of the request body did not match the servers expectation + * `urn:openproject-org:api:v3:errors:InvalidRequestBody` (**HTTP 400**) + The format of the request body did not match the servers expectation - * `urn:openproject-org:api:v3:errors:InvalidRenderContext` (**HTTP 400**) - The client specified a rendering context that does not exist + * `urn:openproject-org:api:v3:errors:InvalidRenderContext` (**HTTP 400**) + The client specified a rendering context that does not exist - * `urn:openproject-org:api:v3:errors:InvalidUserStatusTransition` (**HTTP 400**) - The client used an invalid transition in the attempt to change the status of a user account. + * `urn:openproject-org:api:v3:errors:InvalidUserStatusTransition` (**HTTP 400**) + The client used an invalid transition in the attempt to change the status of a user account. - * `urn:openproject-org:api:v3:errors:Unauthenticated` (**HTTP 401**) - The client has to authenticate to access the requested resource. + * `urn:openproject-org:api:v3:errors:Unauthenticated` (**HTTP 401**) + The client has to authenticate to access the requested resource. - * `urn:openproject-org:api:v3:errors:MissingPermission` (**HTTP 403**) - The client does not have the needed permissions to perform the requested action + * `urn:openproject-org:api:v3:errors:MissingPermission` (**HTTP 403**) + The client does not have the needed permissions to perform the requested action - * `urn:openproject-org:api:v3:errors:NotFound` (**HTTP 404**) - Default for HTTP 404 when no further information is available + * `urn:openproject-org:api:v3:errors:NotFound` (**HTTP 404**) + Default for HTTP 404 when no further information is available - * `urn:openproject-org:api:v3:errors:UpdateConflict` (**HTTP 409**) - The resource changed between GET-ing it and performing an update on it + * `urn:openproject-org:api:v3:errors:UpdateConflict` (**HTTP 409**) + The resource changed between GET-ing it and performing an update on it - * `urn:openproject-org:api:v3:errors:TypeNotSupported` (**HTTP 415**) - The request contained data in an unsupported media type (Content-Type) + * `urn:openproject-org:api:v3:errors:TypeNotSupported` (**HTTP 415**) + The request contained data in an unsupported media type (Content-Type) - * `urn:openproject-org:api:v3:errors:PropertyIsReadOnly` (**HTTP 422**) - The client tried to set or change a property that is not writable + * `urn:openproject-org:api:v3:errors:PropertyIsReadOnly` (**HTTP 422**) + The client tried to set or change a property that is not writable - * `urn:openproject-org:api:v3:errors:PropertyConstraintViolation` (**HTTP 422**) - The client tried to set a property to an invalid value + * `urn:openproject-org:api:v3:errors:PropertyConstraintViolation` (**HTTP 422**) + The client tried to set a property to an invalid value - * `urn:openproject-org:api:v3:errors:PropertyValueNotAvailableAnymore` (**HTTP 422**) - An unchanged property needs to be changed, because other changes to the resource make it unavailable + * `urn:openproject-org:api:v3:errors:PropertyValueNotAvailableAnymore` (**HTTP 422**) + An unchanged property needs to be changed, because other changes to the resource make it unavailable - * `urn:openproject-org:api:v3:errors:ResourceTypeMismatch` (**HTTP 422**) - A link to a resource of a specific type was expected, but the link to another type of resource was provided + * `urn:openproject-org:api:v3:errors:ResourceTypeMismatch` (**HTTP 422**) + A link to a resource of a specific type was expected, but the link to another type of resource was provided - * `urn:openproject-org:api:v3:errors:PropertyFormatError` (**HTTP 422**) - A property value was provided in a format that the server does not understand or accept + * `urn:openproject-org:api:v3:errors:PropertyFormatError` (**HTTP 422**) + A property value was provided in a format that the server does not understand or accept - * `urn:openproject-org:api:v3:errors:InternalServerError` (**HTTP 500**) - Default for HTTP 500 when no further information is available + * `urn:openproject-org:api:v3:errors:InternalServerError` (**HTTP 500**) + Default for HTTP 500 when no further information is available - * `urn:openproject-org:api:v3:errors:MultipleErrors` - Multiple errors occurred. See the embedded `errors` array for more details. + * `urn:openproject-org:api:v3:errors:MultipleErrors` + Multiple errors occurred. See the embedded `errors` array for more details. - # Formattable Text + ## Formattable Text OpenProject supports text formatting in Markdown. Properties that contain formattable text have a special representation in this API. In this specification their type is indicated as `Formattable`. Their representation contains the following properties: @@ -191,15 +208,17 @@ description: |- If the *Formattable* is marked as **read only**, the `raw` attribute also becomes **read only**. - #### Example + ##### Example + ```json { - "format": "markdown", - "raw": "I **am** formatted!", - "html": "I am formatted!" - } + "format": "markdown", + "raw": "I **am** formatted!", + "html": "I am formatted!" + } + ``` - # Dates, Times and Durations + ## 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): @@ -210,19 +229,21 @@ description: |- * `Duration` - refers to an ISO 8601 duration, e.g. "P1DT18H" - # Colors + ## Colors Colors are represented in RGB using hexadecimal notation as specified in [CSS Color Module Level 3](http://www.w3.org/TR/css3-color/). That is a `#` followed by either three or six hexadecimal digits. - #### Examples + ##### Example - red: #ff0000 or #f00 + ``` + red: #ff0000 or #f00 green: #00ff00 or #0f0 black: #000000 or #000 white: #ffffff or #fff + ``` - # Digests + ## Digests Digests (or Hashes) are one way functions that map data of arbitrary size to data of a fixed size. In OpenProject they are for example used to calculate checksums for (attachment) files. @@ -235,10 +256,12 @@ description: |- | algorithm | The algorithm used to compute the digest | String | md5 | | hash | The calculated digest in hexadecimal notation | String | 64c26a8403cd796ea4cf913cda2ee4a9 | - #### Example + ##### Example + ```json { - "algorithm": "md5", - "hash": "64c26a8403cd796ea4cf913cda2ee4a9" - } + "algorithm": "md5", + "hash": "64c26a8403cd796ea4cf913cda2ee4a9" + } + ``` name: Basic Objects diff --git a/docs/api/apiv3/tags/collections.yml b/docs/api/apiv3/tags/collections.yml index b95fada0af3..3097c964d4e 100644 --- a/docs/api/apiv3/tags/collections.yml +++ b/docs/api/apiv3/tags/collections.yml @@ -14,8 +14,6 @@ description: |- The available ways of pagination depend on the collection queried. Some collections feature no pagination at all, meaning they will always return all elements. Others might only offer one of the two pagination methods or both of them. - An explanation of [offset](#collections-offset-based-pagination) and [cursor](#collections-cursor-based-pagination) based - pagination can be found below the links table. A collection also carries meta information like the total count of elements in the collection or - in case of a paginated collection - the amount of elements returned in this response and action links to retrieve the remaining elements. diff --git a/docs/api/apiv3/tags/filters.yml b/docs/api/apiv3/tags/filters.yml index cf0e741c10c..530e5d0fbe0 100644 --- a/docs/api/apiv3/tags/filters.yml +++ b/docs/api/apiv3/tags/filters.yml @@ -8,13 +8,13 @@ description: |- - You can combine any number of distinct filters can be added to the endpoint definitions in this API documentation - - A combination of filter objects are treated as an AND filter. OR filters are not yet possible in a single query, but this feature is tracked in https://community.openproject.com/wp/26837 + - A combination of filter objects are treated as an AND filter. OR filters are not yet possible in a single query. ## Filter syntax The filter syntax is a JSON object that can be passed as a GET parameter to the endpoints as an URL-encoded JSON string looks like the following: - ``` + ```json [ { "": { "operator": "", "values": [, ...] }, ... @@ -25,7 +25,7 @@ description: |- Filtering the work packages API endpoint for a work package that matches the subject or ID "12" and has a status with the ID=5. - ``` + ```json [ { "subjectOrId": { "operator": "**", values: ["12"] } }, { "status": { "operator": "=", values: ["5"] } } @@ -59,7 +59,7 @@ description: |- All of the props can be put inside a json object - ``` + ```json { "filters": "[{\"subjectOrId\":{\"operator\":\"**\",\"values\":[\"12\"]}},{\"status\":{\"operator\":\"=\",\"values\":[\"5\"]}}]", "sortBy": "[[\"id\",\"asc\"]]", diff --git a/docs/api/apiv3/tags/forms.yml b/docs/api/apiv3/tags/forms.yml index ce75d74ead4..f1c9cc8cb2d 100644 --- a/docs/api/apiv3/tags/forms.yml +++ b/docs/api/apiv3/tags/forms.yml @@ -63,7 +63,7 @@ description: |- ### Schema - The schema embedded in a form is a normal [schema describing the underlying resource](#schema). + The schema embedded in a form is a normal [schema describing the underlying resource](https://www.openproject.org/docs/api/endpoints/schemas/). However, the embedded schema can change with each revalidation of the form. For example it might be possible, that changing the type of a work package affects its available properties, as well as possible values for certain properties. @@ -71,7 +71,7 @@ description: |- ### Validation Errors - Like a [schema](#schema) the validation errors build a dictionary where the key is a property name. + Like a schema the validation errors build a dictionary where the key is a property name. Each value is an error object that indicates the error that occurred validating the corresponding property. There are only key value pairs for properties that failed validation, the element is empty if all validations succeeded. diff --git a/docs/api/apiv3/tags/principals.yml b/docs/api/apiv3/tags/principals.yml index 2007b0fe7aa..42cd100ba74 100644 --- a/docs/api/apiv3/tags/principals.yml +++ b/docs/api/apiv3/tags/principals.yml @@ -3,11 +3,4 @@ description: |- Principals are the superclass of users, groups and placeholder users. This end point returns all principals within a joined collection but can be filtered to e.g. only return groups or users. - ## Linked Properties - - See [user](#users) and [group](#groups) - - ## Local Properties - - See [user](#users) and [group](#groups) and placeholder users (TDB) name: Principals diff --git a/docs/api/apiv3/tags/projects.yml b/docs/api/apiv3/tags/projects.yml index c9dae2acf0e..be58e564f06 100644 --- a/docs/api/apiv3/tags/projects.yml +++ b/docs/api/apiv3/tags/projects.yml @@ -31,7 +31,7 @@ description: |- Note, that the parent link may contain the "undisclosed uri" `urn:openproject-org:api:v3:undisclosed` in case a parent project is defined but the client lacks permission to see it. See the - [general introduction into links' properties](/docs/api/basic-objects/#header-local-properties-1) for more information. + [general introduction into links' properties](https://www.openproject.org/docs/api/basic-objects/#local-properties) for more information. ## Local Properties diff --git a/docs/api/apiv3/tags/queries.yml b/docs/api/apiv3/tags/queries.yml index 18c345e7da1..8d5407dcd69 100644 --- a/docs/api/apiv3/tags/queries.yml +++ b/docs/api/apiv3/tags/queries.yml @@ -60,7 +60,7 @@ description: |- The list of values can either consist of a list of links or of a list of strings. If the values are primitive (e.g. Integer, Boolean, Date) they will be displayed as strings and the QueryFilterInstance will have a `values` property. - ``` + ```json { "_type": "DueDateQueryFilter", "name": "Finish date", @@ -85,7 +85,7 @@ description: |- If the values are nonprimitive (e.g. User, Project), they will be listed as objects and the QueryFilterInstance will have a `values` link. - ``` + ```json { "_type": "AssigneeQueryFilter", "name": "Assignee", diff --git a/docs/api/apiv3/tags/query_columns.yml b/docs/api/apiv3/tags/query_columns.yml index 782c59481be..a38f9df6ccc 100644 --- a/docs/api/apiv3/tags/query_columns.yml +++ b/docs/api/apiv3/tags/query_columns.yml @@ -1,12 +1,9 @@ --- description: |- - A QueryColumn can be referenced by a Query to denote the work package properties the client should display for the work packages returned as query results. The columns maps to the WorkPackage by the id property. QueryColumns exist in three types: QueryColumn::Property, QueryColumn::RelationToType and QueryColumn::RelationOfType. + A QueryColumn can be referenced by a Query to denote the work package properties the client should display for the work packages returned as query results. The columns maps to the WorkPackage by the id property. QueryColumns exist in three types: `QueryColumn::Property`, `QueryColumn::RelationToType` and `QueryColumn::RelationOfType`. ## Actions - | Link | Description | Condition | - |:-------------------:|----------------------------------------------------------------------| ---------------------------------------| - As of now, no actions are defined. ## Linked Properties diff --git a/docs/api/apiv3/tags/query_filters.yml b/docs/api/apiv3/tags/query_filters.yml index 78e5bfaca75..fb6db7ae694 100644 --- a/docs/api/apiv3/tags/query_filters.yml +++ b/docs/api/apiv3/tags/query_filters.yml @@ -4,9 +4,6 @@ description: |- ## Actions - | Link | Description | Condition | - |:-------------------:|----------------------------------------------------------------------| ---------------------------------------| - As of now, no actions are defined. ## Linked Properties diff --git a/docs/api/apiv3/tags/query_operators.yml b/docs/api/apiv3/tags/query_operators.yml index 32ebb2f82a3..8d0bd899748 100644 --- a/docs/api/apiv3/tags/query_operators.yml +++ b/docs/api/apiv3/tags/query_operators.yml @@ -4,9 +4,6 @@ description: |- ## Actions - | Link | Description | Condition | - |:-------------------:|----------------------------------------------------------------------| ---------------------------------------| - As of now, no actions are defined. ## Linked Properties diff --git a/docs/api/apiv3/tags/query_sort_bys.yml b/docs/api/apiv3/tags/query_sort_bys.yml index 98e97e5a169..5734ce67964 100644 --- a/docs/api/apiv3/tags/query_sort_bys.yml +++ b/docs/api/apiv3/tags/query_sort_bys.yml @@ -4,9 +4,6 @@ description: |- ## Actions - | Link | Description | Condition | - |:-------------------:|----------------------------------------------------------------------| ---------------------------------------| - As of now, no actions are defined. ## Linked Properties diff --git a/docs/api/apiv3/tags/schemas.yml b/docs/api/apiv3/tags/schemas.yml index 6105b7de957..5b256f70741 100644 --- a/docs/api/apiv3/tags/schemas.yml +++ b/docs/api/apiv3/tags/schemas.yml @@ -18,7 +18,7 @@ description: |- | :-----------------: | ---------------------------------------------------------------------------------- | ---------------- | | _dependencies | A list of dependencies between one property's value and another property | SchemaDependency | - The `_dependencies` property contains the list of dependencies that exist between the value selected for one of the properties of the described resource and the resource's structure. Depending on the value, additional properties might exist or properties might have other values allowed to be assigned. See [SchemaDependency](#schema-dependencies) for more information. + The `_dependencies` property contains the list of dependencies that exist between the value selected for one of the properties of the described resource and the resource's structure. Depending on the value, additional properties might exist or properties might have other values allowed to be assigned. See [SchemaDependency](https://www.openproject.org/docs/api/endpoints/schemas/#schema-dependencies) for more information. # Field schema @@ -33,7 +33,7 @@ description: |- This is an optimization to allow efficient handling of both small resource lists (that can be enumerated inline) and large resource lists (requiring one or more separate requests). - The `allowedValuesSchemas` will on rare occasions (e.g. for a [Query](#query)) replace `allowedValues`. This is done when there is no fixed set of allowed values. Instead, the allowed values will have to follow a schema, or one of a list of schemas, in its own right. + The `allowedValuesSchemas` will on rare occasions (e.g. for a [Query](https://www.openproject.org/docs/api/endpoints/queries/)) replace `allowedValues`. This is done when there is no fixed set of allowed values. Instead, the allowed values will have to follow a schema, or one of a list of schemas, in its own right. Only one of the links (`allowedValues`, `allowedValuesSchemas`) will exist for any given property. @@ -74,9 +74,6 @@ description: |- ## Linked Properties - | Link | Description | Type | Nullable | Supported operations | - |:-------------------:| ---------------------------------------- | ------------- | -------- | -------------------- | - A SchemaDependency does not have any links. ## Local Properties diff --git a/docs/api/apiv3/tags/work_packages.yml b/docs/api/apiv3/tags/work_packages.yml index 6b83063da9c..fca900ed6a4 100644 --- a/docs/api/apiv3/tags/work_packages.yml +++ b/docs/api/apiv3/tags/work_packages.yml @@ -86,6 +86,7 @@ description: |- `startDate` can also not be earlier than a finish date of any predecessor. While attachments are returned as a link which's content is to be fetched separately, clients can choose to - replace the work package's attachments by providing an array of already uploaded [Attachment resources](#attachments) on [create](#work-packages-work-packages-post) - and [update](#work-packages-work-package-patch). The attachments the work package has had prior to the request will be removed. + replace the work package's attachments by providing an array of already uploaded [Attachment resources](https://www.openproject.org/docs/api/endpoints/attachments/) + on [create](https://www.openproject.org/docs/api/endpoints/work-packages/#create-work-package) + and [update](https://www.openproject.org/docs/api/endpoints/work-packages/#edit-work-package). The attachments the work package has had prior to the request will be removed. name: Work Packages diff --git a/docs/api/bcf/bcf-rest-api.md b/docs/api/bcf/bcf-rest-api.md index 7afa4b1ee69..baa35920c64 100644 --- a/docs/api/bcf/bcf-rest-api.md +++ b/docs/api/bcf/bcf-rest-api.md @@ -7,7 +7,7 @@ The following describes the extensions and deviations of the BCF API v2.1 implem This document should be read as an extension to the [standard specification](https://github.com/buildingSMART/BCF-API/blob/release_2_1/README.md). The user should read the standard specification first, and then take a look at this document to be informed about OpenProject specificities. -While the intend of the implementation is to follow the specification, the API builds on the existing OpenProject data +While the intent of the implementation is to follow the specification, the API builds on the existing OpenProject data schema and by that requires to map between the concepts required in the much broader domain of project management and BCF. In other parts, the BCF API specification has not been completely implemented. It will be amended where requirements dictate. diff --git a/docs/enterprise-guide/enterprise-on-premises-guide/README.md b/docs/enterprise-guide/enterprise-on-premises-guide/README.md index 6070961118c..7f87ac56dff 100644 --- a/docs/enterprise-guide/enterprise-on-premises-guide/README.md +++ b/docs/enterprise-guide/enterprise-on-premises-guide/README.md @@ -26,5 +26,5 @@ The Enterprise on-premises edition builds on top of the free Community edition. | [Activate Enterprise on-premises](./activate-enterprise-on-premises) | How can I upgrade my Community edition to an Enterprise on-premises edition? | | [Support](./support) | How can I get support or installation support? | - + diff --git a/docs/system-admin-guide/initial-setup/README.md b/docs/system-admin-guide/initial-setup/README.md index 1118da89966..41bf76120fb 100644 --- a/docs/system-admin-guide/initial-setup/README.md +++ b/docs/system-admin-guide/initial-setup/README.md @@ -29,6 +29,7 @@ Before adding users we recommend to check and configure the following topics: | [Start page](../../user-guide/start-page) | Set up the home page, shown after login | If required, especially for on-premises versions, it might make sense to have a look at these sections, too: + | Topic | What to set up | | ------------------------------------------------------------ | :----------------------------------------------------------- | | [Configure outbound emails](../../installation-and-operations/configuration/outbound-emails/) | Set up SMTP on the server to send email | diff --git a/docs/user-guide/roadmap/README.md b/docs/user-guide/roadmap/README.md index fd6f363faa8..fb9c2a660cc 100644 --- a/docs/user-guide/roadmap/README.md +++ b/docs/user-guide/roadmap/README.md @@ -9,7 +9,9 @@ keywords: roadmap, release planning # Product roadmap release planning -
**Roadmap** is defined as an overview page displaying the versions sorted alphabetically and the work packages assigned to them. The roadmap is displayed in the project navigation when the work package module is activated and a version has been created (project settings).
+
+**Roadmap** is defined as an overview page displaying the versions sorted alphabetically and the work packages assigned to them. The roadmap is displayed in the project navigation when the work package module is activated and a version has been created (project settings). +
Plan and manage your product roadmap in OpenProject. Visualize, and communicate your product roadmap. Share your product roadmap with your stakeholders, get feedback about your ideas and break it down into a detailed release plan.