kanbanworkflowstimelinescrumrubyroadmapproject-planningproject-managementopenprojectangularissue-trackerifcgantt-chartganttbug-trackerboardsbcf
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
113 lines
5.8 KiB
113 lines
5.8 KiB
## Introduction
|
|
|
|
The APIv3 is a hypermedia REST API, a shorthand for "Hypermedia As The Engine Of Application State" (HATEOAS).
|
|
This means that each endpoint of this API will have links to other resources or actions defined in the resulting body.
|
|
|
|
These related resources and actions for any given resource will be context sensitive. For example, only actions that the
|
|
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
|
|
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
|
|
|
|
**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
|
|
|
|
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).
|
|
However in this API you have the guarantee that whenever a resource is **embedded**, it is embedded in its **full representation**.
|
|
|
|
## API response structure
|
|
|
|
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).
|
|
|
|
# Authentication
|
|
|
|
The API supports the following authentication schemes: OAuth2, session based authentication, and basic auth.
|
|
|
|
Depending on the settings of the OpenProject instance many resources can be accessed without being authenticated.
|
|
In case the instance requires authentication on all requests the client will receive an **HTTP 401** status code
|
|
in response to any request.
|
|
|
|
Otherwise unauthenticated clients have all the permissions of the anonymous user.
|
|
|
|
## 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
|
|
|
|
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.
|
|
|
|
Example:
|
|
|
|
```bash
|
|
API_KEY=2519132cdf62dcf5a66fd96394672079f9e9cad1
|
|
curl -u apikey:$API_KEY https://community.openproject.com/api/v3/users/42
|
|
```
|
|
|
|
## OAuth2.0 authentication
|
|
|
|
OpenProject allows authentication and authorization with OAuth2 with *Authorization code flow*, as well as *Client credentials* operation modes.
|
|
|
|
To get started, you first need to register an application in the OpenProject OAuth administration section of your installation.
|
|
This will save an entry for your application with a client unique identifier (`client_id`) and an accompanying secret key (`client_secret`).
|
|
|
|
You can then use one the following guides to perform the supported OAuth 2.0 flows:
|
|
|
|
- [Authorization code flow](https://oauth.net/2/grant-types/authorization-code)
|
|
- [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?
|
|
|
|
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.
|
|
|
|
Using **username and password** directly would have some advantages:
|
|
|
|
* It is intuitive for the user who then just has to provide those just as they would when logging into OpenProject.
|
|
* No extra logic for token management necessary.
|
|
|
|
On the other hand using **API keys** has some advantages too, which is why we went for that:
|
|
|
|
* If compromised while saved on an insecure client the user only has to regenerate the API key instead of changing their password, too.
|
|
* They are naturally long and random which makes them invulnerable to dictionary attacks and harder to crack in general.
|
|
|
|
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)
|
|
|
|
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
|
|
how to selectively enable CORS.
|
|
|
|
|
|
# Allowed HTTP methods
|
|
|
|
- `GET` - Get a single resource or collection of resources
|
|
- `POST` - Create a new resource or perform
|
|
- `PATCH` - Update a resource
|
|
- `DELETE` - Delete a resource
|
|
|
|
# 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).
|
|
If no `Accept-Encoding` header is send, `Accept-Encoding: identity` is assumed which will result in the API responding uncompressed.
|
|
|