9.2 KiB
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 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.
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:
authorization_code_grant- 4.1 - Authorization Code Grantclient_credentials- 4.4 - Client Credentials Grant
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
implicit_grant- 4.2 - Implicit Grantresource_owner_password_credentials_grant- 4.3 - Resource Owner Password Credentials Grant 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 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
- viewTopic - The ability to see topics (see 4.2.3 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_typebim_snippet.is_externalbim_snippet.referencebim_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