BCF REST API

BCF REST API Icon

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

Not implemented

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