Oliver Günther
5 years ago
committed by
GitHub
commit
ac9abbafa5
@ -0,0 +1,15 @@ |
||||
module NoRoutingErrorLogging |
||||
def log_error(env, wrapper) |
||||
super unless ignore_error?(env, wrapper) |
||||
end |
||||
|
||||
def ignore_error?(env, wrapper) |
||||
!Rails.logger.debug? && routing_error?(env, wrapper) |
||||
end |
||||
|
||||
def routing_error?(_env, wrapper) |
||||
wrapper.exception.is_a? ActionController::RoutingError |
||||
end |
||||
end |
||||
|
||||
ActionDispatch::DebugExceptions.prepend NoRoutingErrorLogging if Rails.env.production? |
||||
@ -0,0 +1,510 @@ |
||||
# BCF REST API in OpenProject |
||||
 |
||||
|
||||
The following describes the extensions and deviations of the BCF API v2.1 implementation in OpenProject. |
||||
|
||||
While the intend 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. |
||||
OpenProject offers a second API (v3) which might be able to fill the gaps the BCF API implementation still has. |
||||
|
||||
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. |
||||
|
||||
The document follows the structure of the standard specification to ease comparing the two documents. |
||||
|
||||
**Table of Contents** |
||||
|
||||
<!-- toc --> |
||||
|
||||
- [1. Introduction](#1-introduction) |
||||
* [1.1 Paging, Sorting and Filtering](#11-paging-sorting-and-filtering) |
||||
* [1.2 Caching](#12-caching) |
||||
* [1.3 Updating Resources via HTTP PUT](#13-updating-resources-via-http-put) |
||||
* [1.4 Cross Origin Resource Sharing (CORS)](#14-cross-origin-resource-sharing-cors) |
||||
* [1.5 Http Status Codes](#15-http-status-codes) |
||||
* [1.6 Error Response Body Format](#16-error-response-body-format) |
||||
* [1.7 DateTime Format](#17-datetime-format) |
||||
* [1.8 Authorization](#18-authorization) |
||||
+ [1.8.1 Per-Entity Authorization](#181-per-entity-authorization) |
||||
+ [1.8.2 Determining Authorized Entity Actions](#182-determining-authorized-entity-actions) |
||||
* [1.9 Additional Response and Request Object Properties](#19-additional-response-and-request-object-properties) |
||||
* [1.10 Binary File Uploads](#110-binary-file-uploads) |
||||
- [2. Topologies](#2-topologies) |
||||
* [2.1 Topology 1 - BCF-Server only](#21-topology-1---bcf-server-only) |
||||
* [2.2 Topology 2 - Colocated BCF-Server and Model Server](#22-topology-2---colocated-bcf-server-and-model-server) |
||||
- [3. Public Services](#3-public-services) |
||||
* [3.1 Versions Service](#31-versions-service) |
||||
* [3.2 Authentication Services](#32-authentication-services) |
||||
+ [3.2.1 Obtaining Authentication Information](#321-obtaining-authentication-information) |
||||
+ [3.2.2 OAuth2 Example](#322-oauth2-example) |
||||
+ [3.2.3 OAuth2 Protocol Flow - Dynamic Client Registration](#323-oauth2-protocol-flow---dynamic-client-registration) |
||||
* [3.3 User Services](#33-user-services) |
||||
+ [3.3.1 Get current user](#331-get-current-user) |
||||
- [4. BCF Services](#4-bcf-services) |
||||
* [4.1 Project Services](#41-project-services) |
||||
+ [4.1.1 GET Projects Service](#411-get-projects-service) |
||||
+ [4.1.2 GET Project Service](#412-get-project-service) |
||||
+ [4.1.3 PUT Project Service](#413-put-project-service) |
||||
+ [4.1.4 GET Project Extension Service](#414-get-project-extension-service) |
||||
+ [4.1.5 Expressing User Authorization Through Project Extensions](#415-expressing-user-authorization-through-project-extensions) |
||||
- [4.1.5.1 Project](#4151-project) |
||||
- [4.1.5.2 Topic](#4152-topic) |
||||
- [4.1.5.3 Comment](#4153-comment) |
||||
* [4.2 Topic Services](#42-topic-services) |
||||
+ [4.2.1 GET Topics Service](#421-get-topics-service) |
||||
+ [4.2.2 POST Topic Service](#422-post-topic-service) |
||||
+ [4.2.3 GET Topic Service](#423-get-topic-service) |
||||
+ [4.2.4 PUT Topic Service](#424-put-topic-service) |
||||
+ [4.2.5 DELETE Topic Service](#425-delete-topic-service) |
||||
+ [4.2.6 GET Topic BIM Snippet Service](#426-get-topic-bim-snippet-service) |
||||
+ [4.2.7 PUT Topic BIM Snippet Service](#427-put-topic-bim-snippet-service) |
||||
+ [4.2.8 Determining Allowed Topic Modifications](#428-determining-allowed-topic-modifications) |
||||
* [4.3 File Services](#43-file-services) |
||||
+ [4.3.1 GET Files (Header) Service](#431-get-files-header-service) |
||||
+ [4.3.2 PUT Files (Header) Service](#432-put-files-header-service) |
||||
* [4.4 Comment Services](#44-comment-services) |
||||
+ [4.4.1 GET Comments Service](#441-get-comments-service) |
||||
+ [4.4.2 POST Comment Service](#442-post-comment-service) |
||||
+ [4.4.3 GET Comment Service](#443-get-comment-service) |
||||
+ [4.4.4 PUT Comment Service](#444-put-comment-service) |
||||
+ [4.4.5 DELETE Comment Service](#445-delete-comment-service) |
||||
+ [4.4.6 Determining allowed Comment modifications](#446-determining-allowed-comment-modifications) |
||||
* [4.5 Viewpoint Services](#45-viewpoint-services) |
||||
+ [4.5.1 GET Viewpoints Service](#451-get-viewpoints-service) |
||||
+ [4.5.2 POST Viewpoint Service](#452-post-viewpoint-service) |
||||
- [4.5.2.1 Point](#4521-point) |
||||
- [4.5.2.2 Direction](#4522-direction) |
||||
- [4.5.2.3 Orthogonal camera](#4523-orthogonal-camera) |
||||
- [4.5.2.4 Perspective camera](#4524-perspective-camera) |
||||
- [4.5.2.5 Line](#4525-line) |
||||
- [4.5.2.6 Clipping plane](#4526-clipping-plane) |
||||
- [4.5.2.7 Bitmap](#4527-bitmap) |
||||
- [4.5.2.8 Snapshot](#4528-snapshot) |
||||
- [4.5.2.9 Components](#4529-components) |
||||
- [4.5.2.10 Component](#45210-component) |
||||
* [Optimization rules](#optimization-rules) |
||||
- [4.5.2.11 Coloring](#45211-coloring) |
||||
* [Optimization rules](#optimization-rules-1) |
||||
- [4.5.2.12 Visibility](#45212-visibility) |
||||
* [Optimization rules](#optimization-rules-2) |
||||
- [4.5.2.13 View setup hints](#45213-view-setup-hints) |
||||
+ [4.5.3 GET Viewpoint Service](#453-get-viewpoint-service) |
||||
+ [4.5.4 GET Viewpoint Snapshot Service](#454-get-viewpoint-snapshot-service) |
||||
+ [4.5.5 GET Viewpoint Bitmap Service](#455-get-viewpoint-bitmap-service) |
||||
+ [4.5.6 GET selected Components Service](#456-get-selected-components-service) |
||||
+ [4.5.7 GET colored Components Service](#457-get-colored-components-service) |
||||
+ [4.5.8 GET visibility of Components Service](#458-get-visibility-of-components-service) |
||||
* [4.6 Related Topics Services](#46-related-topics-services) |
||||
+ [4.6.1 GET Related Topics Service](#461-get-related-topics-service) |
||||
+ [4.6.2 PUT Related Topics Service](#462-put-related-topics-service) |
||||
* [4.7 Document Reference Services](#47-document-reference-services) |
||||
+ [4.7.1 GET Document References Service](#471-get-document-references-service) |
||||
+ [4.7.2 POST Document Reference Service](#472-post-document-reference-service) |
||||
+ [4.7.3 PUT Document Reference Service](#473-put-document-reference-service) |
||||
* [4.8 Document Services](#48-document-services) |
||||
+ [4.8.1 GET Documents Service](#481-get-documents-service) |
||||
+ [4.8.2 POST Document Service](#482-post-document-service) |
||||
+ [4.8.3 GET Document Service](#483-get-document-service) |
||||
* [4.9 Topics Events Services](#49-topics-events-services) |
||||
+ [4.9.1 GET Topics Events Service](#491-get-topics-events-service) |
||||
+ [4.9.2 GET Topic Events Service](#492-get-topic-events-service) |
||||
* [4.10 Comments Events Services](#410-comments-events-services) |
||||
+ [4.10.1 GET Comments Events Service](#4101-get-comments-events-service) |
||||
+ [4.10.2 GET Comment Events Service](#4102-get-comment-events-service) |
||||
|
||||
<!-- tocstop --> |
||||
|
||||
# 1. Introduction |
||||
|
||||
All end points are nested within the `/api` path. So for a server listening on `https://foo.com/` the API root will be |
||||
`https://foo.com/api/bcf/2.1`. For a server listening on `https://foo.com/bar` the API root will be |
||||
`https://foo.com/bar/api/bcf/2.1`. |
||||
|
||||
## 1.1 Paging, Sorting and Filtering |
||||
|
||||
_Not implemented_ |
||||
|
||||
## 1.2 Caching |
||||
|
||||
_Implemented_ |
||||
|
||||
## 1.3 Updating Resources via HTTP PUT |
||||
|
||||
_Implemented_ |
||||
|
||||
## 1.4 Cross Origin Resource Sharing (CORS) |
||||
|
||||
_Not implemented_ |
||||
|
||||
## 1.5 Http Status Codes |
||||
|
||||
_Implemented_ |
||||
|
||||
## 1.6 Error Response Body Format |
||||
|
||||
_Implemented_ |
||||
|
||||
## 1.7 DateTime Format |
||||
|
||||
_Implemented_ |
||||
|
||||
## 1.8 Authorization |
||||
|
||||
_Implemented_ |
||||
|
||||
Authorization is granted based on the _view_linked_issues_ and the _manage_bcf_ permission. As BCFs share part of their |
||||
data structure with WorkPackages, which enables them to be worked on by the project team just like any other work package, |
||||
a user also needs to have the _view_work_packages_ permission to have _view_linked_issues_. For _manage_bcf_ the permissions |
||||
_view_work_packages_, _add_work_packages_, _edit_work_packages_ and _delete_work_packages_ are dependently required. |
||||
|
||||
### 1.8.1 Per-Entity Authorization |
||||
|
||||
_Implemented_ |
||||
|
||||
The `authorization` field is always returned, regardless of an `includeAuthorization` query parameter. |
||||
|
||||
### 1.8.2 Determining Authorized Entity Actions |
||||
|
||||
_Implemented_ |
||||
|
||||
## 1.9 Additional Response and Request Object Properties |
||||
|
||||
The implementation relies on a client to particularly adhere to this. |
||||
|
||||
## 1.10 Binary File Uploads |
||||
|
||||
_Implemented_ |
||||
|
||||
# 2. Topologies |
||||
|
||||
_Out of scope_ |
||||
|
||||
# 3. Public Services |
||||
|
||||
## 3.1 Versions Service |
||||
|
||||
_Not implemented_ |
||||
|
||||
## 3.2 Authentication Services |
||||
|
||||
### 3.2.1 Obtaining Authentication Information |
||||
|
||||
_Implemented_ |
||||
|
||||
The following OAuth2 flows are supported: |
||||
* `authorization_code_grant` - [4.1 - Authorization Code Grant](https://tools.ietf.org/html/rfc6749#section-4.1) |
||||
* `client_credentials` - [4.4 - Client Credentials Grant](https://tools.ietf.org/html/rfc6749#section-4.4) |
||||
|
||||
The `clients_credentials` grant explicitly ruled out by the standard specification as not being user specific can be supported by OpenProject as the grant is mapped to a user account |
||||
when configuring the OAuth access. |
||||
|
||||
Before a client is able to perform the flows, they need to be [configured in OpenProject](https://docs.openproject.org/system-admin-guide/authentication/oauth-applications/). `bcf_v2_1` needs |
||||
to be checked for the scope. That value also needs to be provided for the scope property in OAuth requests. |
||||
|
||||
The OAuth2 flows alternatively proposed by the specification |
||||
* `implicit_grant` - [4.2 - Implicit Grant](https://tools.ietf.org/html/rfc6749#section-4.2) |
||||
* `resource_owner_password_credentials_grant` - [4.3 - Resource Owner Password Credentials Grant](https://tools.ietf.org/html/rfc6749#section-4.3) |
||||
are not implemented. |
||||
|
||||
### 3.2.2 OAuth2 Example |
||||
|
||||
_Out of scope_ |
||||
|
||||
### 3.2.3 OAuth2 Protocol Flow - Dynamic Client Registration |
||||
|
||||
_Not implemented_ |
||||
|
||||
## 3.3 User Services |
||||
|
||||
### 3.3.1 Get current user |
||||
|
||||
_Implemented_ |
||||
|
||||
# 4. BCF Services |
||||
|
||||
## 4.1 Project Services |
||||
|
||||
The `project_id` is an integer value. However, the API also understands requests where the project identifier, e.g. `bcf_project` |
||||
is used instead of the integer within a url. So the following urls might point to the same project resource: `/api/bcf/2.1/projects/3` and `/api/bcf/2.1/projects/bcf_project`. |
||||
|
||||
### 4.1.1 GET Projects Service |
||||
|
||||
_Partly implemented_ |
||||
|
||||
The end point is implemented but lacks the `authorization` property. However, the [Project Extension Service](#414-get-project-extension-service) is completely implemented and provides the same information. |
||||
|
||||
### 4.1.2 GET Project Service |
||||
|
||||
_Partly implemented_ |
||||
|
||||
The end point is implemented but lacks the `authorization` property. However, the [Project Extension Service](#414-get-project-extension-service) is completely implemented and provides the same information. |
||||
|
||||
### 4.1.3 PUT Project Service |
||||
|
||||
_Implemented_ |
||||
|
||||
### 4.1.4 GET Project Extension Service |
||||
|
||||
_Implemented and extended_ |
||||
|
||||
However, as some end points are not implemented, the actions indicating the ability to call those end points will also not be returned, e.g. `updateDocumentReferences` |
||||
|
||||
### 4.1.5 Expressing User Authorization Through Project Extensions |
||||
|
||||
_Out of scope_ |
||||
|
||||
#### 4.1.5.1 Project |
||||
|
||||
_Implemented and extended_ |
||||
|
||||
* *viewTopic* - The ability to see topics (see [4.2.3 GET Topic Service](#423-get-topic-service)) |
||||
|
||||
#### 4.1.5.2 Topic |
||||
|
||||
_Implemented_ |
||||
|
||||
#### 4.1.5.3 Comment |
||||
|
||||
_Implemented_ |
||||
|
||||
## 4.2 Topic Services |
||||
|
||||
BCF topics are tightly coupled to work packages in OpenProject. This coupling is denoted in the `reference_links` property |
||||
of a topic which will always have a link to the work package resource in the API v3. e.g.: |
||||
|
||||
<-- other properties --> |
||||
"reference_links": [ |
||||
"/api/v3/work_packages/92" |
||||
], |
||||
<-- other properties --> |
||||
|
||||
### 4.2.1 GET Topics Service |
||||
|
||||
_Partly implemented_ |
||||
|
||||
The following properties are not supported: |
||||
* `labels` (the property exists but cannot be written and is always empty) |
||||
* `stage` (the property exists but cannot be written and is always null) |
||||
* `bim_snippet.snippet_type` |
||||
* `bim_snippet.is_external` |
||||
* `bim_snippet.reference` |
||||
* `bim_snippet.reference_schema` |
||||
|
||||
OData sort, filtering and pagination is not supported. |
||||
|
||||
### 4.2.2 POST Topic Service |
||||
|
||||
_Partly implemented_ |
||||
|
||||
See [4.2.3 GET Topic Service](#423-get-topic-service) for details. |
||||
|
||||
Either a new work package is created or, if a work package is referenced in the `reference_links` section, a the referenced |
||||
work package is associated to the newly created topic. A work package can only be associated to one topic and vice versa. |
||||
|
||||
### 4.2.3 GET Topic Service |
||||
|
||||
_Partly implemented_ |
||||
|
||||
See [4.2.3 GET Topic Service](#423-get-topic-service) for details. |
||||
|
||||
### 4.2.4 PUT Topic Service |
||||
|
||||
_Partly implemented_ |
||||
|
||||
The reference to the work package cannot be altered. |
||||
|
||||
See [4.2.3 GET Topic Service](#423-get-topic-service) for details. |
||||
|
||||
### 4.2.5 DELETE Topic Service |
||||
|
||||
_Implemented_ |
||||
|
||||
The associated work package will also be deleted. |
||||
|
||||
### 4.2.6 GET Topic BIM Snippet Service |
||||
|
||||
_Not implemented_ |
||||
|
||||
### 4.2.7 PUT Topic BIM Snippet Service |
||||
|
||||
_Not implemented_ |
||||
|
||||
## 4.3 File Services |
||||
|
||||
### 4.3.1 GET Files (Header) Service |
||||
|
||||
_Not implemented_ |
||||
|
||||
### 4.3.2 PUT Files (Header) Service |
||||
|
||||
_Not implemented_ |
||||
|
||||
## 4.4 Comment Services |
||||
|
||||
### 4.4.1 GET Comments Service |
||||
|
||||
_Not implemented_ |
||||
|
||||
### 4.4.2 POST Comment Service |
||||
|
||||
_Not implemented_ |
||||
|
||||
### 4.4.3 GET Comment Service |
||||
|
||||
_Not implemented_ |
||||
|
||||
### 4.4.4 PUT Comment Service |
||||
|
||||
_Not implemented_ |
||||
|
||||
### 4.4.5 DELETE Comment Service |
||||
|
||||
_Not implemented_ |
||||
|
||||
### 4.4.6 Determining allowed Comment modifications |
||||
|
||||
_Not implemented_ |
||||
|
||||
## 4.5 Viewpoint Services |
||||
|
||||
### 4.5.1 GET Viewpoints Service |
||||
|
||||
_Implemented_ |
||||
|
||||
### 4.5.2 POST Viewpoint Service |
||||
|
||||
_Implemented_ |
||||
|
||||
#### 4.5.2.1 Point |
||||
|
||||
_Implemented_ |
||||
|
||||
#### 4.5.2.2 Direction |
||||
|
||||
_Implemented_ |
||||
|
||||
#### 4.5.2.3 Orthogonal camera |
||||
|
||||
_Implemented_ |
||||
|
||||
#### 4.5.2.4 Perspective camera |
||||
|
||||
_Implemented_ |
||||
|
||||
#### 4.5.2.5 Line |
||||
|
||||
_Implemented_ |
||||
|
||||
#### 4.5.2.6 Clipping plane |
||||
|
||||
_Implemented_ |
||||
|
||||
#### 4.5.2.7 Bitmap |
||||
|
||||
_Implemented_ |
||||
|
||||
#### 4.5.2.8 Snapshot |
||||
|
||||
_Implemented_ |
||||
|
||||
#### 4.5.2.9 Components |
||||
|
||||
_Implemented_ |
||||
|
||||
#### 4.5.2.10 Component |
||||
|
||||
_Implemented_ |
||||
|
||||
#### 4.5.2.11 Coloring |
||||
|
||||
_Implemented_ |
||||
|
||||
#### 4.5.2.12 Visibility |
||||
|
||||
_Implemented_ |
||||
|
||||
#### 4.5.2.13 View setup hints |
||||
|
||||
_Implemented_ |
||||
|
||||
### 4.5.3 GET Viewpoint Service |
||||
|
||||
_Implemented_ |
||||
|
||||
### 4.5.4 GET Viewpoint Snapshot Service |
||||
|
||||
_Implemented_ |
||||
|
||||
### 4.5.6 GET selected Components Service |
||||
|
||||
_Implemented_ |
||||
|
||||
### 4.5.7 GET colored Components Service |
||||
|
||||
_Implemented_ |
||||
|
||||
### 4.5.8 GET visibility of Components Service |
||||
|
||||
_Implemented_ |
||||
|
||||
## 4.6 Related Topics Services |
||||
|
||||
### 4.6.1 GET Related Topics Service |
||||
|
||||
_Not implemented_ |
||||
|
||||
### 4.6.2 PUT Related Topics Service |
||||
|
||||
_Not implemented_ |
||||
|
||||
## 4.7 Document Reference Services |
||||
|
||||
### 4.7.1 GET Document References Service |
||||
|
||||
_Not implemented_ |
||||
|
||||
### 4.7.2 POST Document Reference Service |
||||
|
||||
_Not implemented_ |
||||
|
||||
### 4.7.3 PUT Document Reference Service |
||||
|
||||
_Not implemented_ |
||||
|
||||
## 4.8 Document Services |
||||
|
||||
### 4.8.1 GET Documents Service |
||||
|
||||
_Not implemented_ |
||||
|
||||
### 4.8.2 POST Document Service |
||||
|
||||
_Not implemented_ |
||||
|
||||
### 4.8.3 GET Document Service |
||||
|
||||
_Not implemented_ |
||||
|
||||
## 4.9 Topics Events Services |
||||
|
||||
### 4.9.1 GET Topics Events Service |
||||
|
||||
_Not implemented_ |
||||
|
||||
### 4.9.2 GET Topic Events Service |
||||
|
||||
_Not implemented_ |
||||
|
||||
## 4.10 Comments Events Services |
||||
|
||||
_Not implemented_ |
||||
|
||||
### 4.10.1 GET Comments Events Service |
||||
|
||||
_Not implemented_ |
||||
|
||||
### 4.10.2 GET Comment Events Service |
||||
|
||||
_Not implemented_ |
||||
Loading…
Reference in new issue