Skip to content

Instantly share code, notes, and snippets.

@NobodysNightmare

NobodysNightmare/example.apib

Created January 20, 2015 09:19
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save NobodysNightmare/5095a25d6f1c9662db46 to your computer and use it in GitHub Desktop.
Save NobodysNightmare/5095a25d6f1c9662db46 to your computer and use it in GitHub Desktop.
Download ZIP
Shortened spec
Raw
example.apib
FORMAT: 1A
# OpenProject API v3
# Group General
This is the current **DRAFT** of the specification for OpenProject APIv3.
Please note that everything in this document might be **subject to change** in a future version of OpenProject. We intend to keep this specification
as accurate as possible, however as long as the APIv3 is not in a stable state it is possible that there are intermediary differences between
this specification and the real implementation. While we try to only specify what we want to keep, it might also happen that parts of this
specification will be replaced **incompatibly** until the APIv3 is considered *stable*.
# Hypermedia
TODO: Description & Resources
# Formats
TODO: Description and why only JSON
# HAL+JSON
HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API.
Read more: http://stateless.co/hal_specification.html
**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 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
For now the API only supports **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.
However for the future we plan to add authentication modes that are more suitable for **external clients** too.
# 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
# Group Basic Objects
# Links
Links to other resources in the API are represented uniformly by so called link objects.
## Properties
| Property | Description | Type | Required | Nullable | Default |
|:---------:| ------------------------------------------------------------------------ | ------- |:--------:|:--------:| ------- |
| href | URL to the referenced resource (might be relative) | String | ✓ | ✓ | |
| title | Representative label for the resource | String | | | |
| templated | If true the `href` contains parts that need to be replaced by the client | Boolean | | | false |
| method | The HTTP verb to use when requesting the resource | String | | | GET |
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.
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.
Templated links are links that contain client replacable parts. Replaceable parts are enclosed in braces. For example
the link `api/v3/example/{id}` is not complete in itself, but the client needs to replace the string `{id}` itself.
As of now the API does not indicate the valid replacement values.
The `method` indicates which HTTP verb the client *must* use when following the link for the intended purpose.
Note: When writing links (e.g. during a `PATCH` operation) only changes to `href` are accepted.
Changes to all other properties will be **silently ignored**.
# Errors
In case of an error, the API will respond with an apropriate 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 errorneous response.
## General errors
* Error objects have their `_type` set to `Error`
* The `errorIdentifier` serves as a unique (and machine readable) identifier for a specific error cause
* There *may* be multiple possible error identifiers per HTTP status code
* There *may* be multiple possible HTTP status codes per error identifier
* The "List of Error Identifiers" defines the possible mappings between HTTP status and error identifier
* The `message` contains a human readable concise message describing the error
* It *optionally* includes specific information, for example which permission would have been needed to perform an action
* It is localized depending on the users preferences
* It *must not* include HTML or other kind of markup
* Error messages form complete sentences including punctuation
### Example
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:InternalServerError",
"message": "An internal server error occured. This is not your fault."
}
## Embedded error information
Errors might optionally contain embedded objects that contain further information.
### 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
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:examples:ExampleError",
"message": "This is an example error.",
"_embedded": {
"details": {
"_type": "ExampleErrorDetailInformation",
"errorneousField": "subject"
}
}
}
### 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.
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 occured.
#### Example
{
"_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",
"...": "..."
}
]
}
}
## List of Error Identifiers
* `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: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:MissingPermission` (**HTTP 401** / **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:UpdateConflict` (**HTTP 409**) - The resource changed between GET-ing it and performing an update on it
* `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: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:InternalServerError` (**HTTP 500**) - Default for HTTP 500 when no further information is available
* `urn:openproject-org:api:v3:errors:MultipleErrors` - Multiple errors occured. See the embedded `errors` array for more details.
# Formatable Text
OpenProject supports text formatting in Textile. Other text formats *may* be introduced in the future.
Properties that contain formatable text have a special representation in this API. In this specification their
type is indicated as `Formatable`. Their representation contains the following properties:
| Property | Description | Type | Example | Supported operations |
|:--------:| -------------------------------------------------- | ------ | ---------------------------------- | -------------------- |
| format | Indicates the formatting language of the raw text | String | textile | READ |
| raw | The raw text, as entered by the user | String | `I *am* formatted!` | READ / WRITE |
| html | The text converted to HTML according to the format | String | `I <strong>am</strong> formatted!` | READ |
`format` can as of today have one of the following values:
* `plain` - no formatting at all
* `textile` - formatting using Textile
More formats might be added in the future.
Note that `raw` is the only property supporting the **write** operation. A property of type *Formatable* that
is marked as **read and write**, will only accept changes to the `raw` property. Changes to `format` and `html` will be **silently ignored**.
It is thus sufficient to solely provide the `raw` property for changes.
If the *Formatable* is marked as **read only**, the `raw` attribute also becomes **read only**.
#### Example
{
"format": "textile",
"raw": "I *am* formatted!",
"html": "I <strong>am</strong> formatted!"
}
# 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):
* `Date` - refers to an ISO 8601 date, e.g. "2014-05-21"
* `DateTime` - refers to an ISO 8601 combined date and time, e.g. "2014-05-21T13:37:00Z"
* `Duration` - refers to an ISO 8601 duration, e.g. "P1DT18H"
# 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
red: #ff0000 or #f00
green: #00ff00 or #0f0
black: #000000 or #000
white: #ffffff or #fff
# Group Collections
Whenever a client calls a resource that can return more than one element, it will receive a collection of elements.
However as collections can become quite large, the API will **not** simply return a JSON array, but a special collection
object that will contain the actual elements in its embedded property `elements`.
Collections *may* be paginated, this means that a single response from the server will not contain all elements of the collection,
but only a subset. In this case the client can issue further requests to retrieve the remaining elements.
There are two ways to access the result pages of a paginated collection:
* offset based pagination
* cursor based pagination
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.
## Properties
| Property | Description | Type | Availability |
|:--------:| --------------------------------------------------------------- | ------- | --------------------------- |
| total | The total amount of elements available in the collection | Integer | always |
| pageSize | Amount of elements that a response will hold | Integer | when paginated |
| count | Actual amount of elements in this response | Integer | always |
| offset | Amount of elements preceding the first element of this response | Integer | when offset based available |
## Links
| Link | Description | Availability |
|:----------------:| ------------------------------------------------------------------------ | --------------------------- |
| self | Link to the current page in the collection | always |
| changeSize | Templated link to change the page size, preserving the relative position | when paginated |
| filter | Templated link to receive only elements matching the provided OQL query | when filtering available |
| jumpTo | Templated link to jump to a specified offset | when offset based available |
| nextByOffset | Link to retrieve the following page of elements (offset based) | when offset based available |
| previousByOffset | Link to retrieve the preceding page of elements (offset based) | when offset based available |
| nextByCursor | Link to retrieve the elements following the current page (cursor based) | when cursor based available |
| previousByCursor | Link to retrieve the elements preceding the current page (cursor based) | when cursor based available |
### Filters
Filters are specified using the [OpenProject Query Language (OQL)](https://github.com/opf/oql).
The syntax of OQL queries is explained in the [OQL Documentation](http://www.rubydoc.info/github/opf/oql/dev). All properties of the underlying resource can be used
in the query, e.g. when filtering over a collection of work packages, it is possible to compare the `subject` with any value.
Note that for linked resources you can either compare against the **ID** of the linked resource or against its **link URL**:
# valid
status == "1"
status == "/api/v3/statuses/1"
# NOT valid
status == "New"
## Offset based pagination [/api/v3/examples{?offset,pageSize}]
Offset based pagination works by specifying two values: the **offset** and the **pageSize**. The offset determines how many elements are
skipped before the first element that is present in the result. The page size determines how many items there will be in the result. Note
that the server might not allow arbitrarily large page sizes, a client should therefore always check the page size accepted by the server
using the **pageSize** property of the response.
The benefit of offset based pagination is that the total number of pages can be easily determined and that it is possible to jump
to arbitrary pages within the collection. Offset based pagination is therefore well suited when a result is displayed to the end user
in the form of multiple pages anyway.
A drawback of offset based pagination comes with concurrent modification of the collection. If the collection is modified
between two page requests, it is possible that the client receives elements close to the page boundaries twice or does not see them at all.
## view offset based [GET]
+ Parameters
+ offset = `0` (optional, integer, `25`) ... Number of elements to skip before the first element of the response.
+ pageSize (optional, integer, `25`) ... Number of elements to display per page.
+ Response 200 (application/hal+json)
+ Body
{
"_links": {
"self": { "href": "/api/v3/examples?offset=25&pageSize=25" },
"jumpTo": {
"href": "/api/v3/examples?offset={offset}&pageSize=25",
"templated": true
},
"changeSize": {
"href": "/api/v3/examples?offset=25&pageSize={size}",
"templated": true
},
"previousByOffset": { "href": "/api/v3/examples?offset=0&pageSize=25" },
"previousByCursor": { "href": "/api/v3/examples?before=bar&pageSize=25" }
},
"_type": "Collection",
"total": 27,
"pageSize": 25,
"count": 2,
"offset": 25,
"_embedded": {
"elements": [
{ "foo": "bar" },
{ "foo": "baz" }
]
}
}
## Cursor based pagination [/api/v3/examples{?before,after,pageSize}]
Cursor based pagination is intended to be used, when the client needs a consistent and complete (sub-) range of the collection,
e.g. in infinite scrolling scenarios. In cursor based pagination the client will receive a link to the next and
the previous page in the result set. The guarantee is, that the boundaries of that page will align with the boundaries of the current page,
regardless of changes to the collection.
The drawback for cursor based pagination is, that it is not immediately determinable how many "next" and how many "previous" pages there are.
Cursor based pagination is therefore less suited for use cases where you want to directly "jump" to an arbitrary page.
## view cursor based [GET]
+ Parameters
+ before (optional, string, `bar`) ... Display the elements preceding the given element.
Note that the value of this parameter is very specific to the collection, a client should not
try to infer values, but use the **previous** link offered by the collection.
+ after (optional, string, `buz`) ... Display the elements succeeding the given element.
Note that the value of this parameter is very specific to the collection, a client should not
try to infer values, but use the **next** link offered by the collection.
+ pageSize (optional, integer, `25`) ... Number of elements to display per page.
+ Response 200 (application/hal+json)
+ Body
{
"_links": {
"self": { "href": "/api/v3/examples?after=buz&pageSize=25" },
"changeSize": {
"href": "/api/v3/examples?after=buz&pageSize={size}",
"templated": true
},
"previousByCursor": { "href": "/api/v3/examples?before=bar&pageSize=25" }
},
"_type": "Collection",
"total": 27,
"pageSize": 25,
"count": 2,
"_embedded": {
"elements": [
{ "foo": "bar" },
{ "foo": "baz" }
]
}
}
# Group Attachments
## Properties:
| Property | Description | Type | Constraints | Supported operations |
| :---------: | ------------- | ---- | ----------- | -------------------- |
| id | Attachment's id | Integer | x > 0 | READ |
| fileName | | String | | READ |
| diskFileName | | String | | READ |
| description | | String | | READ |
| contentType | | String | | READ |
| digest | | String | | READ |
| downloads | | Integer | | READ |
| createdAt | Time of creation | DateTime | | READ |
## Attachment [/api/v3/attachments/{id}]
+ Model
+ Body
{
"_type": "Attachment",
"_links": {
"self": {
"href": "/api/v3/attachments/1",
"title": "dolor_sit_amet"
},
"workPackage" {
"href": "/api/v3/work_packages/1",
"title": "Lorem ipsum"
},
"author": {
"href": "/api/v3/users/1",
"title": "John Sheppard - admin"
}
},
"id": 1,
"fileName": "dolor_sit_amet",
"diskFileName": "dolor_sit_amet",
"description": "Lorem ipsum dolor sit amet consecetur elis.",
"filesize": 24,
"contentType": "application/binary",
"digest": "",
"downloads": 0,
"createdAt": "2014-05-21T08:51:20Z"
}
## View attachment [GET]
+ Parameters
+ id (required, integer, `1`) ... Attachment id
+ Response 200 (application/hal+json)
[Attachment][]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment