Nepenthes

Appearance

BCF REST API ​

The following describes the extensions and deviations of the BCF API v2.1 implementation in OpenProject.

This document should be read as an extension to the standard specification. The user should read the standard specification first, and then take a look at this document to be informed about OpenProject specificities.

While the intent 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.

The document follows the structure of the standard specification to ease comparing the two documents.

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:

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. 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

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 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 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

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 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 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 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