API: Views

A View is a representation of some information. That information might be a query (currently it always is). The view will store the configuration on how to display the information but not the information itself.

A View might then be a graph, a table, a gantt chart or something completely different. The client will have to choose how to represenent in the view.

A View instance will always be of a subtype of Views, e.g. Views::WorkPackageslist. The properties between each Views type might differ a lot.

The View is a new concept so it is prone to change.

Currently a lot of restrictions still apply:

  • There will always be a query associated to the view when in the complete concept, this limitation should not be necessary.
  • A query can only have one view associated.
  • There is neither an update nor a delete endpoint and the schema and form endpoints are also missing. To delete a view, simply delete the query.
  • Most of the properties are deduced from the associated query and can thus only be updated via updating the query.
  • The properties are not different between Views subtypes.

Linked Properties

Link Description Type Constraints Supported operations
self This view View (a subtype of it) not null READ
query This query from which to fetch the data Query not null READ/WRITE
project This project the view is defined in (deduces from the query). If no project is specified, the View is considered global. Project Deduced from the query READ

Local Properties

Property Description Type Constraints Supported operations
_type The subtype chosen String READ
id View id Integer x > 0 READ
name View name String Deduced from the query READ
public Can users besides the owner see the view? Boolean Deduced from the query READ
starred Should the view be highlighted to the user? Boolean Deduced from the query READ
createdAt Time of creation DateTime not null READ
updatedAt Time of the most recent change to the view DateTime not null READ

Methods

List views

Returns a collection of Views. The collection can be filtered via query parameters similar to how work packages are filtered.

filters
string

optional query

JSON specifying filter conditions. Currently supported filters are:

  • project: filters views by the project their associated query is assigned to. If the project filter is passed with the !* (not any) operator, global views are returned.

  • id: filters views based on their id

  • type: filters views based on their type

Example:
[{ "project_id": { "operator": "!*", "values": null }" }]

200

OK

{
  "_links": {
    "self": {
      "href": "/api/v3/views"
    },
    "changeSize": {
      "href": "/api/v3/views?pageSize={size}",
      "templated": true
    },
    "jumpTo": {
      "href": "/api/v3/views?offset={offset}",
      "templated": true
    }
  },
  "total": 1,
  "count": 1,
  "_type": "Collection",
  "_embedded": {
    "elements": [
      {
        "_type": "Views::WorkPackagesTable",
        "name": "Current work packages",
        "timelineVisible": true,
        "id": 9,
        "_links": {
          "self": {
            "href": "/api/v3/views/9"
          },
          "query": {
            "href": "/api/v3/queries/18",
            "title": "A query"
          },
          "columns": [
            {
              "href": "/api/v3/users/id",
              "title": "ID"
            },
            {
              "href": "/api/v3/users/subject",
              "title": "Subject"
            },
            {
              "href": "/api/v3/users/type",
              "title": "Type"
            },
            {
              "href": "/api/v3/users/status",
              "title": "Status"
            },
            {
              "href": "/api/v3/users/priority",
              "title": "Priority"
            },
            {
              "href": "/api/v3/users/assignee",
              "title": "Assignee"
            },
            {
              "href": "/api/v3/users/updated_at",
              "title": "Updated on"
            }
          ],
          "project": {
            "href": "/api/v3/project/89",
            "title": "The project"
          }
        }
      }
    ]
  }
}

View view

id
integer

required path

View id

Example:
42

200

Returns the result of a single view, dependent of the view type.

{
  "_type": "Views::WorkPackagesTable",
  "name": "Current work packages",
  "id": 9,
  "_links": {
    "self": {
      "href": "/api/v3/views/9"
    },
    "query": {
      "href": "/api/v3/queries/18",
      "title": "Current work packages"
    },
    "project": {
      "href": "/api/v3/project/89",
      "title": "The project"
    }
  }
}

{
  "_type": "Views::TeamPlanner",
  "name": "Product team",
  "id": 9,
  "_links": {
    "self": {
      "href": "/api/v3/views/9"
    },
    "query": {
      "href": "/api/v3/queries/18",
      "title": "Product team"
    },
    "project": {
      "href": "/api/v3/project/89",
      "title": "The project"
    }
  }
}

400

Occurs when the client did not send a valid JSON object in the request body.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
  "message": "The request body was not a single JSON object."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

403

Returned if the client does not have sufficient permissions.

Required permission: The required permission depends on the type of the view.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to access this resource."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

404

Returned if the resource can not be found.

Note: A client without sufficient permissions shall not be able to test for the existence of a view. That’s why a 404 is returned here, even if a 403 might be more appropriate.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The requested resource could not be found."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

Create view

When calling this endpoint the client provides a single object, containing at least the properties and links that are required, in the body. The required fields of a View can be found in its schema, which is embedded in the respective form. Note that it is only allowed to provide properties or links supporting the write operation.

There are different subtypes of Views (e.g. Views::WorkPackagesTable) with each having its own endpoint for creating that subtype e.g.

  • /api/v3/views/work_packages_table for Views::WorkPackagesTable
  • /api/v3/views/team_planner for Views::TeamPlanner
  • /api/v3/views/work_packages_calendar for Views::WorkPackagesCalendar

Not yet implemented To get the list of available subtypes and by that the endpoints for creating a subtype, use the

  /api/v3/views/schemas

endpoint.

id
string

required path

The view identifier

Example:
1

{
  "type": "object",
  "properties": {
    "_links": {
      "type": "object",
      "properties": {
        "query": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string",
              "format": "uri"
            }
          }
        }
      }
    }
  }
}

201

Created

{
  "_type": "Views::WorkPackagesTable",
  "name": "Current work packages",
  "id": 9,
  "_links": {
    "self": {
      "href": "/api/v3/views/9"
    },
    "query": {
      "href": "/api/v3/queries/18",
      "title": "Current work packages"
    },
    "project": {
      "href": "/api/v3/project/89",
      "title": "The project"
    }
  }
}

{
  "_type": "Views::TeamPlanner",
  "name": "Product team",
  "id": 9,
  "_links": {
    "self": {
      "href": "/api/v3/views/9"
    },
    "query": {
      "href": "/api/v3/queries/18",
      "title": "Product team"
    },
    "project": {
      "href": "/api/v3/project/89",
      "title": "The project"
    }
  }
}

{
  "type": "object"
}

400

Occurs when the client did not send a valid JSON object in the request body.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
  "message": "The request body was not a single JSON object."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

406

Occurs when the client did not send a Content-Type header

"Missing content-type header"

{
  "type": "string"
}

415

Occurs when the client sends an unsupported Content-Type header.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
  "message": "Expected CONTENT-TYPE to be (expected value) but got (actual value)."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

422

Returned if:

  • the client tries to modify a read-only property (PropertyIsReadOnly)

  • a constraint for a property was violated (PropertyConstraintViolation)

  • the client provides a link to an invalid resource (ResourceTypeMismatch), e.g. a query not found

{
  "_embedded": {
    "details": {
      "attribute": "query"
    }
  },
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
  "message": "Query does not exist."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}