__Be aware:__ The API v2 is marked as deprecated. Please read this [news article](https://www.openproject.org/news/65-api-v1-and-api-v2-deprecated-v3-in-development) for more information on that.
# General Information
## Authentication
The API supports both *basic auth* and authentication via an *API access key*. The latter is transmitted either as one of the parameters, named `key`, for a request or in the request header `X-OpenProject-API-Key`.
You can find a user's API key on their account page (/my/account).
The value in parenthesis is the `Content-Type` for the respective format to be transmitted when writing data (_POST_, _PUT_).
This header has to be transmitted even though the format is already indicated by the URL, e.g. when it ends with `.xml`.
## Terminology
What is referred to as _planning elements_ within the API (v2) is actually a _work package_ as far as the web interface is concerned. In previous versions the same thing may have been referred to as _issues_.
## Placeholders
In the rest of this document the string @:format@ will be used in URLs as a placeholder for an arbitrary format chosen from the available formats given above. I.e. you can substitute either `xml` or `json` for any occurrence of `:format`.
There is another placeholder called `:project_id`. This can either be substituted with a project's ID within the database or a project's _identifier_.
Furthermore the placeholder `:planning_element_id` has to be substituted with a planning element's ID within the database.
*Examples:*
The URL @/api/v2/projects/:project_id/edit@ can become:
*`/api/v2/projects/2/edit`
*`/api/v2/projects/maintenance/edit`
# API
__Be aware__ This section may be incomplete. Only _planning elements_ and _custom fields_ are described at the moment and even those sections may not be complete.
Shows **all**_planning elements_ of a given _project_. For each _planning element_ a subset of the available information will be listed.
Example XML response excerpt:
```xml
<?xml version=""1.0"" encoding=""UTF-8""?>
<planning_elementstype=""array"">
<planning_element>
<idtype=""integer"">2</id>
<subject>magni sint culpa</subject>
<!-- ... -->
</planning_element>
<!-- more planning elements ... -->
</planning_elements>
```
### Index (filtered)
*TODO: Explain that _:project_id_ can in fact be a set of projects, identifiers or ids, that are comma-separated in the URL.*
Planning Elements can also be filtered using Query strings that correspond to work package filters. It is possible to filter on several conditions that are combined with logical AND. The following is an example filtering planning elements on `status_id`.
The above query string corresponds to the following key-value pairs:
```
f[] => status_id
op[status_id] => =
v[status_id][] => 5
```
* The first key, `f[]`, defines a list of fields that are being filtered. In this example, we only filter for `status_id`.
* The `op[*]` keys define the operator for each field that is being filtered. The operator used here is the equal operator, which specifies that the `status_id` of the planning elements must be equal to one of the values provided.
* The `v[*][]` key defines the values on the right side of the operation. Here, the id 5 is provided, which results in the following combined statement:
The _status_id_ needs to _equal__5_.
The following constitutes a more complex query, combining two filters, one of which is an OR-combination of values:
The above query string corresponds to the following key-value pairs:
```
f[] => type_id
op[type_id] => =
v[type_id][] => 3
f[] => status_id
op[status_id] => =
v[status_id][] => 5
v[status_id][] => 2
```
* The @f[]@ key is being set twice, which is being interpreted as an array of @[type_id, status_id]@ being assigned to @f[]@.
* The operatorts are subsequently set to the equal operator. Both @op[type_id]@ as well as @op[status_id]@ are set to @=@.
* The value field @v[type_id][]@ is set to 3. The value field @v[status_id][]@ is set twice, and like @f[]@, results in the array @[5, 2]@ being assigned as possible values. This results in the following combined statement:
The _type_id_ needs to _equal__3_ AND the _status_id_ needs to _equal_ either _5_ OR _2_.
The available operators can be found in the ""@Queries::Filter@"":https://github.com/opf/openproject/blob/dev/app/models/queries/filter.rb#L41-L74 class. Some of the available field options can be found in the ""@Queries::WorkPackages::AvailableFilterOptions@"":https://github.com/opf/openproject/blob/dev/app/models/queries/work_packages/available_filter_options.rb#L45-L56 class. The response when filtering planning elements is of the exact same structure than the unfiltered index action:
```
<?xml version=""1.0"" encoding=""UTF-8""?>
<planning_elementstype=""array"">
<planning_element>
<idtype=""integer"">2</id>
<subject>magni sint culpa</subject>
<!-- ... -->
</planning_element>
<!-- more planning elements ... -->
</planning_elements>
```
There is a caveat when filtering trees of planning elements. When there are parent_ids in planning elements that correspond to planning elements that have been filtered out, i.e. the filter removes the parent of a planning element, then the parent_id of the planning elements is adjusted to the closest ancestor that is not filtered out. This could cause confusion when updating planning elements to the values that the server sent from a filtered query. The response to a filter can and occasionally will have objectively wrong parent_ids in favour of a reconstructable tree on the client side.
Updates a _planning element_. In addition to the usual attributes you can of course also update its _custom field values_. The request body for that in XML could look like this:
```
<?xml version=""1.0"" encoding=""UTF-8""?>
<planning_element>
<subject>Bug in front page</subject>
<custom_fieldstype=""array"">
<custom_field>
<id>4</id>
<value>pending</value>
</custom_field>
</custom_fields>
</planning_element>
```
Similarly when using JSON it would look like this:
```
{
""planning_element"": {
""custom_fields"": [
{
""id"": 4,
""value"": ""pending""
}
],
""subject"": ""Bug in front page""
}
}
```
Those requests would set a _planning element's_ subject to ""Bug in front page"" and the value for the _custom field_ with the ID 4 to 'pending'.
A _custom field's_ ID can be found out by querying the available _custom fields_ as described in the _Custom Fields_ section.
You can find out about possible _planning element_ fields by querying a projects _planning elements_ which is described in the _Show_ section.
Shows all projects for the OpenProject instance. Returns the following structure:
```
<?xml version=""1.0"" encoding=""UTF-8""?>
<projectstype=""array"">
<project>
<idtype=""integer"">1</id>
<name>Seeded Project</name>
<identifier>seeded_project</identifier>
<description>
Aut facilis sit officia quasi autem temporibus aut. Id culpa debitis non recusandae quibusdam dolor. Esse et et quaerat hic sapiente et. Voluptatem iste cupiditate consequatur eius laborum. Velit aspernatur provident est corrupti est. Consectetur error veritatis reprehenderit voluptas sint.
""description"": ""Aut facilis sit officia quasi autem temporibus aut. Id culpa debitis non recusandae quibusdam dolor. Esse et et quaerat hic sapiente et. Voluptatem iste cupiditate consequatur eius laborum. Velit aspernatur provident est corrupti est. Consectetur error veritatis reprehenderit voluptas sint."",
""id"": 1,
""identifier"": ""seeded_project"",
""name"": ""Seeded Project"",
""parent_id"": null,
""project_type_id"": null,
""responsible_id"": null,
""type_ids"": [
1,
2,
3,
4,
5,
6
],
""updated_on"": ""2013-11-20T10:01:01Z""
},
{
""created_on"": ""2013-11-20T13:51:42Z"",
""description"": """",
""id"": 2,
""identifier"": ""test"",
""name"": ""Test"",
""parent_id"": null,
""project_type_id"": null,
""responsible_id"": 1,
""type_ids"": [
1,
2,
3,
4,
5,
6
],
""updated_on"": ""2013-12-17T08:59:52Z""
}
]
}
```
### Index (some)
It is possible to retrieve only a set of projects, however not dynamically filtered. To retrieve only a set of projects from the index action, it is possible to query with a list of comma-separated ids or identifiers.
Ids and identifiers can be interchanged, providing identification for a project multiple times will not trigger multiple occurances of that project in the response.
Providing only one id in the field of ids will result in only one project being returned, which is still different from the show action.
Reportings can also be filtered based on the projects involved. One of the involved projects needs to conform to the specified query parameters. Reportings filters support:
* Project types via the @project_types@ field.
* Project status via the @project_statuses@ field.
* Responsible via the @project_responsibles@ field.
The above query string corresponds to the following key-value pairs:
```
only => via_target
project_types => 2
project_statuses => 13
project_responsibles => -1,1
```
The values can be comma-separated lists of ids. A _-1_ value in the list stands for the _(none)_ value, i.e. the field is allowed not to be set (nil). It is also possible to filter for timelines first level grouping criteria as well as project parents in general. The relevant filters can be found in ""Api::V2::ReportingsController"":https://github.com/opf/openproject/blob/dev/app/controllers/api/v2/reportings_controller.rb#L95-L165.
## Project Associations
*This API endpoint is deprecated!* _Don't use it!_
Users can not be indexed w/o specific ids. To retrieve some users, their ids must be provided in the query string as a comma seperated list.
It is possible that users that exist will not be returned when their id is provided. Only users that stisfy the visibility condition will be returned, all other users will be omitted in the result. The visible condition is defined in the ""@Principal@"":https://github.com/opf/openproject/blob/dev/app/models/principal.rb#L87-L95 class.
_GET_ @/api/v2/users.:format?ids=:user_ids@
```
<?xml version=""1.0"" encoding=""UTF-8""?>
<userstype=""array"">
<user>
<idtype=""integer"">1</id>
<firstname>OpenProject</firstname>
<lastname>Admin</lastname>
<name>OpenProject Admin</name>
</user>
</users>
```
The corresponding JSON:
```
{
""users"": [
{
""firstname"": ""OpenProject"",
""id"": 1,
""lastname"": ""Admin"",
""name"": ""OpenProject Admin""
}
]
}
```
## Workflows
### Index
* Related Tickets
** #3113
A list of workflows is a list of ""<code>type</code>"":https://www.openproject.org/projects/openproject/wiki/API_v2/#14-Planning-Element-Types / ""<code>status</code>"":https://www.openproject.org/projects/openproject/wiki/API_v2/#18-Statuses pairs and their respective transitions. Transitions are ""<code>status</code>"":https://www.openproject.org/projects/openproject/wiki/API_v2/#18-Statuses / <code>scope</code> pairs.
A <code>scope</code> can have one of three values <code>role</code>|<code>author</code>|<code>assignee</code>. Thus, if atransition has the scope <code>author</code>, only a user who is author of the respective ticket may be allowed to use this transition. The same is valid for <code>assignee</code>. The scope <code>role</code> is valid in the cases where the user is neither author or assignee.
