From 180affbfc75f72602ad6262ffca933b5d5658b4e Mon Sep 17 00:00:00 2001 From: Yoram Kulbak Date: Fri, 20 Nov 2020 12:36:10 +1100 Subject: [PATCH 1/4] Extract the Foundation from BCF. Add a reference to the Open CDE Foundation API specification. Leave the Authorization section in BCF, for now. --- OAuth2Examples.md | 90 ------------------------------- README.md | 132 ++++++---------------------------------------- 2 files changed, 15 insertions(+), 207 deletions(-) delete mode 100644 OAuth2Examples.md diff --git a/OAuth2Examples.md b/OAuth2Examples.md deleted file mode 100644 index 10c466a..0000000 --- a/OAuth2Examples.md +++ /dev/null @@ -1,90 +0,0 @@ -# BCF API OAuth2 Example - -This example describes an example OAuth2 workflow using the _Authorization Code Grant_ flow as per [section 4.1 of the OAuth2 specification](https://tools.ietf.org/html/rfc6749#section-4.1). Uris of required endpoints are assumed to have been obtained from the authentication resource as described in [section 3.2 of the BCF API specification](https://github.com/BuildingSMART/BCF-API#321-obtaining-authentication-information). - -For this example, it is assumed that the client has been registered with the server in advance and has been issued valid credentials in the form of `client_id` and `client_secret`. - -## Client Request - -To initiate the workflow, the client sends the user to the **"oauth2\_auth_url"** with the following parameters added: - -|parameter|value| -|-------------|------| -|response_type|`code` as string literal| -|client_id|your client id| -|state|unique user defined value| - -Example URL: - - GET https://example.com/bcf/oauth2/auth?response_type=code&client_id=&state= - -_On Windows operating systems, it is possible to open the systems default browser by using the url to start a new process._ - -Example redirected URL: - - https://YourWebsite.com/retrieveCode?code=&state= - -The BCF API server will ask the user to confirm that the client may access resources on his behalf. On authorization, the server redirects to an url that has been defined by the client author in advance. The generated `code` parameter will be appended as query parameter. Additionally, the `state` parameter is included in the redirection, it may be used to match server responses to client requests issued by your application. - -If the user denies client access, there will be an `error` query parameter in the redirection indicating an error reason as described in [section 4.1.2.1 of the OAuth2 specification](https://tools.ietf.org/html/rfc6749#section-4.1.2.1). - -## Token Request - -With the obtained _authorization code_, the client is able to request an access token from the server. The **"oauth2\_token_url"** from the authentication resource is used to send token requests to, for example: - - POST https://example.com/bcf/oauth2/token - -**Parameters** - -|parameter|type|description| -|---------|----|-----------| -|access_token|string|The issued OAuth2 token| -|token_type|string|Always `bearer`| -|expires_in|integer|The lifetime of the access token in seconds| -|refresh_token|string|The issued OAuth2 refresh token, one-time-usable only| - -The POST request should be done via HTTP Basic Authorization with your applications `client_id` as the username and your `client_secret` as the password. - -**Example Request** - - POST https://example.com/bcf/oauth2/token?grant_type=authorization_code&code= - -The access token will be returned as JSON in the response body and is an arbitrary string, guaranteed to not exceed 255 characters length. - -**Example Response** - - Response Code: 201 - Created - Body: - { - "access_token": "Zjk1YjYyNDQtOTgwMy0xMWU0LWIxMDAtMTIzYjkzZjc1Y2Jh", - "token_type": "bearer", - "expires_in": "3600", - "refresh_token": "MTRiMjkzZTYtOTgwNC0xMWU0LWIxMDAtMTIzYjkzZjc1Y2Jh" - } - -## Refresh Token Request - -The process to retrieve a refresh token is exactly the same as retrieving a token via the code workflow except the `refresh_token` is sent instead of the `code` parameter and the `refresh_token` grant type is used. - -**Example Request** - - POST https://example.com/bcf/oauth2/token?grant_type=refresh_token&refresh_token= - -The access token will be returned as JSON in the response body and is an arbitrary string, guaranteed to not exceed 255 characters length. - -**Example Response** - - Response Code: 201 - Created - Body: - { - "access_token": "Zjk1YjYyNDQtOTgwMy0xMWU0LWIxMDAtMTIzYjkzZjc1Y2Jh", - "token_type": "bearer", - "expires_in": "3600", - "refresh_token": "MTRiMjkzZTYtOTgwNC0xMWU0LWIxMDAtMTIzYjkzZjc1Y2Jh" - } - -The refresh token can only be used once to retrieve a token and a new refresh token. - -## Requesting Resources - -When requesting other resources the access token must be passed via the `Authorization` header using the `Bearer` scheme (e.g. `Authorization: Bearer Zjk1YjYyNDQtOTgwMy0xMWU0LWIxMDAtMTIzYjkzZjc1Y2Jh`). \ No newline at end of file diff --git a/README.md b/README.md index 31b375e..5d12c34 100644 --- a/README.md +++ b/README.md @@ -4,29 +4,22 @@ # BCF REST API ![](https://raw.githubusercontent.com/BuildingSMART/BCF/master/Icons/BCFicon128.png) -**Version 2.1** based on BCFv2.1. +**Version 2.2** based on BCFv2.1. [BCF XML GitHub repository](https://github.com/BuildingSMART/BCF) +[Version 1.0 of the Open CDE Foundation API specification is available here](https://github.com/BuildingSMART/shared-common-API/tree/v1.0) [Version 1.0 of the BCF API specification is available here](https://github.com/BuildingSMART/BCF-API/tree/v1.0) +[Version 2.1 of the BCF API specification is available here](https://github.com/BuildingSMART/BCF-API/tree/v2.1) **Table of Contents** - [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) - * [1.11 Differences Between null and Empty Lists](#111-differences-between-null-and-empty-lists) + * [1.1 Open CDE Foundation API](#11-open-cde-foundation-api) + * [1.2 Authorization](#18-authorization) + + [1.2.1 Per-Entity Authorization](#181-per-entity-authorization) + + [1.2.2 Determining Authorized Entity Actions](#182-determining-authorized-entity-actions) - [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) @@ -118,7 +111,7 @@ # 1. Introduction -BCF is a format for managing issues on a BIM project. The BCF-API supports the exchange of BCF issues between software applications via a [RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer) web interface, which means that data is exchanged via Url-encoded query parameters and Json bodies over the Http protocol. Every resource described in this API has a corresponding Json schema (schema version draft-03). +BCF is an open standard for managing issues on a BIM project. The BCF-API supports the exchange of BCF issues between software applications via a [RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer) web interface, which means that data is exchanged via Url-encoded query parameters and Json bodies over the Http protocol. Every resource described in this API has a corresponding Json schema (schema version draft-03). Url schemas in this readme are relational to the BCF base servers Url if no absolute values are provided. For security reasons, all API Http traffic should be sent via TLS/SSL over Https connection. Clients and Servers should both enforce secure connections and disallow unsafe connections. @@ -126,84 +119,19 @@ For security reasons, all API Http traffic should be sent via TLS/SSL over Https An example of a client implementation in C# can be found here: [https://github.com/rvestvik/BcfApiExampleClient](https://github.com/rvestvik/BcfApiExampleClient) -## 1.1 Paging, Sorting and Filtering +## 1.1 Open CDE Foundation API -When requesting collections of items, the BCF-API should offer URL parameters according to the OData v4 specification. It can be found at [http://www.odata.org/documentation/](http://www.odata.org/documentation/). +BCF API is a member of the Open CDE API family. All Open CDE APIs are united by a shared common API called [Open CDE Foundation API](https://github.com/buildingSMART/shared-common-API). +The foundation API specifies a small number of services and a few conventions that are common to all Open CDE APIs. All BCF API implementations must implement the Foundation API and follow its conventions and guidelines. +Implementers should start by implementing the Founation API and only then continue to implement the BCF API. -## 1.2 Caching - -ETags, or entity-tags, are an important part of HTTP, being a critical part of caching, and also used in "conditional" requests. - -The ETag response-header field value, an entity tag, provides for an "opaque" cache validator. -The easiest way to think of an etag is as an MD5 or SHA1 hash of all the bytes in a representation. If just one byte in the representation changes, the etag will change. - -ETags are returned in a response to a GET: - - joe@joe-laptop:~$ curl --include http://bitworking.org/news/ - HTTP/1.1 200 Ok - Date: Wed, 21 Mar 2007 15:06:15 GMT - Server: Apache - ETag: "078de59b16c27119c670e63fa53e5b51" - Content-Length: 23081 - … - -The client may send an "If-None-Match" HTTP Header containing the last retrieved etag. If the content has not changed the server returns a status code 304 (not modified) and no response body. - -## 1.3 Updating Resources via HTTP PUT - -Whenever a resource offers the HTTP PUT method to be updated as a whole. - -This means that there is no partial update mechanism for objects but every PUT request is sending the whole object representation. PUT schemas may exclude server generated values that cannot be edited, such as creation dates or authors. - -## 1.4 Cross Origin Resource Sharing (CORS) - -To work with browser based API clients using [Cross Origin Resource Sharing (Cors)](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing), servers will put the `Access-Control-Allow'` headers in the response headers and specifiy who can access the servers Json resources. The client can look for these values and proceed with accessing the resources. - -In a CORS scenario, web clients expect the following headers: -* `Access-Control-Allow-Headers: Authorization, Content-Type, Accept` to allow the `Authorization`, `Content-Type` and `Accept` headers to be used via [XHR requests](https://en.wikipedia.org/wiki/XMLHttpRequest) -* `Access-Control-Allow-Methods: GET, POST, PUT, OPTIONS` to allow the Http methods the API needs -* `Access-Control-Allow-Origin: example.com` to allow XHR requests from the `example.com` domain to the BCF server - -For example, Asp.Net applications in IIS need the following entries in their `web.config` file. `*` means the server allows any values. - - - - - - - - - -## 1.5 Http Status Codes - -The BCF API relies on the regular Http Status Code definitions. Good sources are [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes) or the [HTTP/1.1 Specification](https://tools.ietf.org/html/rfc7231). - -Generally, these response codes shall be used in the API: -* `200 - OK` for `GET` requests that return data or `PUT` requests that update data -* `201 - Created` for `POST` requests that create data - -`POST` and `PUT` requests do usually include the created resource in the response body. Exceptions to this rule are described in the specific section for the resource. - -## 1.6 Error Response Body Format - -BCF-API has a specified error response body format [error.json](Schemas_draft-03/error.json). - -## 1.7 DateTime Format - -DateTime values in this API are supposed to be in ISO 8601 compliant `YYYY-MM-DDThh:mm:ss` format with optional time zone indicators. This is the same format as defined in the Xml `xs:dateTime` type as well as the result of JavaScripts Date.toJson() output. - -For example, `2016-04-28T16:31:12.270+02:00` would represent _Thursday, April 28th, 2016, 16:31:12 (270ms) with a time zone offset of +2 hours relative to UTC._ -Please note that the colon in the timezone offset is optional, so `+02:00` is equivalent to `+0200`. - -To void ambiguity, This specification steps away from ISO 8601 on the topic of DateTime values with no timezone: The ISO 8601 says that DateTime values with no timezone designator are local times - **In BCF all DateTime values with no timezone designator as assumed to be in UTC**. - -## 1.8 Authorization +## 1.2 Authorization API implementors can optionally choose to restrict the actions a user is allowed to perform on the BCF entities via the API. The global default authorizations for all entities are expressed in the project extensions schema and can be locally overridden in the entities themselves. -### 1.8.1 Per-Entity Authorization +### 1.2.1 Per-Entity Authorization Whenever a user requests an update-able entity with the query parameter `includeAuthorization` equal to `true` the server should include an `authorization` field in the entity containing any local variations from the global @@ -211,7 +139,7 @@ authorization defaults for that entity. Using this information clients can decid "Edit" button in the UI displaying the entity depending on the actions permitted for the user or suggest only the options available to the user for choice fields such as topic status. -### 1.8.2 Determining Authorized Entity Actions +### 1.2.2 Determining Authorized Entity Actions The client can calculate the available set of actions for a particular entity by taking the project-wide defaults from the project extensions, then replacing any keys defined in the entity's `authorization` map with the values specified @@ -260,36 +188,6 @@ Indicating that for this topic, the current user can: * place the Topic into `closed` status * leave the Topic `open` or place the topic back into `open` status after closing it -## 1.9 Additional Response and Request Object Properties - -All API response and request Json objects may contain additional properties that are not covered by this specification. -This is to allow server and client implementations freedom to add additional functionality. Servers and clients shall ignore those properties and must not produce errors on additional properties. Servers and clients are not required to preserve these properties. - -## 1.10 Binary File Uploads - -Some endpoints in the BCF API expect binary file uploads, such as [4.8.2 POST Document Service](#482-post-document-service) -or [4.2.7 PUT Topic BIM Snippet Service](#427-put-topic-bim-snippet-service). - -In such cases, files should be sent with the following Http headers: - - Headers: - Content-Type: application/octet-stream; - Content-Length: {Size of file in bytes}; - Content-Disposition: attachment; filename="{Filename.extension}"; - -## 1.11 Differences Between null and Empty Lists - -Some array or list properties and responses can be interpreted differently if they are either `null` or empty. In general, there are two cases to consider. - -**For collection resources:** - -* A collection resource that does not exist should return Http error `404 - Not Found`, e.g. the list of topics for an invalid project id. -* If the resource exists but there are no elements, the returned response should be an empty array `[]`, e.g. the list of topics for a project where no topics exist. - -**For properties:** - -* If a list property is `null` (by explicitly setting it to null or not returning it in the response object at all), the client should not assume that this represents an empty list but instead the property is not present on the response object. Depending on the response object, this can have the same meaning as an empty list (e.g. no components in a viewpoint is the same as an empty list of components), but this can also mean the property is just omitted for optional properties (e.g. no `topic_actions` in an `authorization` object can mean no restrictions). - ---------- # 2. Topologies From 96ca2083ae15d9ea19b13b99421fdaef0226ed60 Mon Sep 17 00:00:00 2001 From: Yoram Kulbak Date: Mon, 23 Nov 2020 14:33:24 +1100 Subject: [PATCH 2/4] Apply review comments --- README.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 5d12c34..cef985c 100644 --- a/README.md +++ b/README.md @@ -4,11 +4,14 @@ # BCF REST API ![](https://raw.githubusercontent.com/BuildingSMART/BCF/master/Icons/BCFicon128.png) -**Version 2.2** based on BCFv2.1. -[BCF XML GitHub repository](https://github.com/BuildingSMART/BCF) +**BCFv2.2** is based on BCFv2.1. + +[BCF XML GitHub repository](https://github.com/BuildingSMART/BCF-XML) [Version 1.0 of the Open CDE Foundation API specification is available here](https://github.com/BuildingSMART/shared-common-API/tree/v1.0) + [Version 1.0 of the BCF API specification is available here](https://github.com/BuildingSMART/BCF-API/tree/v1.0) + [Version 2.1 of the BCF API specification is available here](https://github.com/BuildingSMART/BCF-API/tree/v2.1) **Table of Contents** @@ -111,8 +114,8 @@ # 1. Introduction -BCF is an open standard for managing issues on a BIM project. The BCF-API supports the exchange of BCF issues between software applications via a [RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer) web interface, which means that data is exchanged via Url-encoded query parameters and Json bodies over the Http protocol. Every resource described in this API has a corresponding Json schema (schema version draft-03). -Url schemas in this readme are relational to the BCF base servers Url if no absolute values are provided. +BCF is an open standard for managing issues on a BIM project. The BCF-API supports the exchange of BCF issues between software applications via a [RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer) web interface, which means that data is exchanged via HTTP query parameters and Json bodies. Every resource described in this API has a corresponding Json schema (schema version draft-03). +Url schemas in this README are relative to the BCF servers' base Url unless absolute values are provided. For security reasons, all API Http traffic should be sent via TLS/SSL over Https connection. Clients and Servers should both enforce secure connections and disallow unsafe connections. @@ -123,7 +126,7 @@ An example of a client implementation in C# can be found here: BCF API is a member of the Open CDE API family. All Open CDE APIs are united by a shared common API called [Open CDE Foundation API](https://github.com/buildingSMART/shared-common-API). The foundation API specifies a small number of services and a few conventions that are common to all Open CDE APIs. All BCF API implementations must implement the Foundation API and follow its conventions and guidelines. -Implementers should start by implementing the Founation API and only then continue to implement the BCF API. +Implementers should start by implementing the Foundation API and only then continue to implement the BCF API. ## 1.2 Authorization From 30df3bf701b9ed0e0f67655ff6640fe519577f1b Mon Sep 17 00:00:00 2001 From: Yoram Kulbak Date: Tue, 24 Nov 2020 17:38:10 +1100 Subject: [PATCH 3/4] Change Json to JSON --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index cef985c..30b756e 100644 --- a/README.md +++ b/README.md @@ -114,7 +114,7 @@ # 1. Introduction -BCF is an open standard for managing issues on a BIM project. The BCF-API supports the exchange of BCF issues between software applications via a [RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer) web interface, which means that data is exchanged via HTTP query parameters and Json bodies. Every resource described in this API has a corresponding Json schema (schema version draft-03). +BCF is an open standard for managing issues on a BIM project. The BCF-API supports the exchange of BCF issues between software applications via a [RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer) web interface, which means that data is exchanged via HTTP query parameters and JSON bodies. Every resource described in this API has a corresponding JSON schema (schema version draft-03). Url schemas in this README are relative to the BCF servers' base Url unless absolute values are provided. For security reasons, all API Http traffic should be sent via TLS/SSL over Https connection. Clients and Servers should both enforce secure connections and disallow unsafe connections. From 926874978d9c3b6d5055aa99468485f6f4cf55a6 Mon Sep 17 00:00:00 2001 From: Yoram Kulbak Date: Tue, 24 Nov 2020 17:49:29 +1100 Subject: [PATCH 4/4] Delete the public services section --- README.md | 578 +++++++++++++++++++----------------------------------- 1 file changed, 203 insertions(+), 375 deletions(-) diff --git a/README.md b/README.md index 30b756e..2715645 100644 --- a/README.md +++ b/README.md @@ -20,95 +20,87 @@ - [1. Introduction](#1-introduction) * [1.1 Open CDE Foundation API](#11-open-cde-foundation-api) - * [1.2 Authorization](#18-authorization) - + [1.2.1 Per-Entity Authorization](#181-per-entity-authorization) - + [1.2.2 Determining Authorized Entity Actions](#182-determining-authorized-entity-actions) + * [1.2 Authorization](#12-authorization) + + [1.2.1 Per-Entity Authorization](#121-per-entity-authorization) + + [1.2.2 Determining Authorized Entity Actions](#122-determining-authorized-entity-actions) - [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.2.9 Topic Identifiers](#429-topic-identifiers) - * [4.3 File Services](#43-file-services) - + [4.3.1 GET Project Files Information Service](#431-get-project-files-information-service) - + [4.3.2 GET Files (Header) Service](#432-get-files-header-service) - + [4.3.3 PUT Files (Header) Service](#433-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) +- [3. BCF Services](#3-bcf-services) + * [3.1 Project Services](#31-project-services) + + [3.1.1 GET Projects Service](#311-get-projects-service) + + [3.1.2 GET Project Service](#312-get-project-service) + + [3.1.3 PUT Project Service](#313-put-project-service) + + [3.1.4 GET Project Extension Service](#314-get-project-extension-service) + + [3.1.5 Expressing User Authorization Through Project Extensions](#315-expressing-user-authorization-through-project-extensions) + - [3.1.5.1 Project](#3151-project) + - [3.1.5.2 Topic](#3152-topic) + - [3.1.5.3 Comment](#3153-comment) + * [3.2 Topic Services](#32-topic-services) + + [3.2.1 GET Topics Service](#321-get-topics-service) + + [3.2.2 POST Topic Service](#322-post-topic-service) + + [3.2.3 GET Topic Service](#323-get-topic-service) + + [3.2.4 PUT Topic Service](#324-put-topic-service) + + [3.2.5 DELETE Topic Service](#325-delete-topic-service) + + [3.2.6 GET Topic BIM Snippet Service](#326-get-topic-bim-snippet-service) + + [3.2.7 PUT Topic BIM Snippet Service](#327-put-topic-bim-snippet-service) + + [3.2.8 Determining Allowed Topic Modifications](#328-determining-allowed-topic-modifications) + + [3.2.9 Topic Identifiers](#329-topic-identifiers) + * [3.3 File Services](#33-file-services) + + [3.3.1 GET Project Files Information Service](#331-get-project-files-information-service) + + [3.3.2 GET Files (Header) Service](#332-get-files-header-service) + + [3.3.3 PUT Files (Header) Service](#333-put-files-header-service) + * [3.4 Comment Services](#34-comment-services) + + [3.4.1 GET Comments Service](#341-get-comments-service) + + [3.4.2 POST Comment Service](#342-post-comment-service) + + [3.4.3 GET Comment Service](#343-get-comment-service) + + [3.4.4 PUT Comment Service](#344-put-comment-service) + + [3.4.5 DELETE Comment Service](#345-delete-comment-service) + + [3.4.6 Determining allowed Comment modifications](#346-determining-allowed-comment-modifications) + * [3.5 Viewpoint Services](#35-viewpoint-services) + + [3.5.1 GET Viewpoints Service](#351-get-viewpoints-service) + + [3.5.2 POST Viewpoint Service](#352-post-viewpoint-service) + - [3.5.2.1 Point](#3521-point) + - [3.5.2.2 Direction](#3522-direction) + - [3.5.2.3 Orthogonal camera](#3523-orthogonal-camera) + - [3.5.2.4 Perspective camera](#3524-perspective-camera) + - [3.5.2.5 Line](#3525-line) + - [3.5.2.6 Clipping plane](#3526-clipping-plane) + - [3.5.2.7 Bitmap](#3527-bitmap) + - [3.5.2.8 Snapshot](#3528-snapshot) + - [3.5.2.9 Components](#3529-components) + - [3.5.2.10 Component](#35210-component) * [Optimization rules](#optimization-rules) - - [4.5.2.11 Coloring](#45211-coloring) + - [3.5.2.11 Coloring](#35211-coloring) * [Optimization rules](#optimization-rules-1) - - [4.5.2.12 Visibility](#45212-visibility) + - [3.5.2.12 Visibility](#35212-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.5.9 DELETE Viewpoint Service](#459-delete-viewpoint-service) - + [4.5.10 Determining allowed Viewpoint modifications](#4510-determining-allowed-viewpoint-modifications) - * [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) + - [3.5.2.13 View setup hints](#35213-view-setup-hints) + + [3.5.3 GET Viewpoint Service](#353-get-viewpoint-service) + + [3.5.4 GET Viewpoint Snapshot Service](#354-get-viewpoint-snapshot-service) + + [3.5.5 GET Viewpoint Bitmap Service](#355-get-viewpoint-bitmap-service) + + [3.5.6 GET selected Components Service](#356-get-selected-components-service) + + [3.5.7 GET colored Components Service](#357-get-colored-components-service) + + [3.5.8 GET visibility of Components Service](#358-get-visibility-of-components-service) + + [3.5.9 DELETE Viewpoint Service](#359-delete-viewpoint-service) + + [3.5.10 Determining allowed Viewpoint modifications](#3510-determining-allowed-viewpoint-modifications) + * [3.6 Related Topics Services](#36-related-topics-services) + + [3.6.1 GET Related Topics Service](#361-get-related-topics-service) + + [3.6.2 PUT Related Topics Service](#362-put-related-topics-service) + * [3.7 Document Reference Services](#37-document-reference-services) + + [3.7.1 GET Document References Service](#371-get-document-references-service) + + [3.7.2 POST Document Reference Service](#372-post-document-reference-service) + + [3.7.3 PUT Document Reference Service](#373-put-document-reference-service) + * [3.8 Document Services](#38-document-services) + + [3.8.1 GET Documents Service](#381-get-documents-service) + + [3.8.2 POST Document Service](#382-post-document-service) + + [3.8.3 GET Document Service](#383-get-document-service) + * [3.9 Topics Events Services](#39-topics-events-services) + + [3.9.1 GET Topics Events Service](#391-get-topics-events-service) + + [3.9.2 GET Topic Events Service](#392-get-topic-events-service) + * [3.10 Comments Events Services](#310-comments-events-services) + + [3.10.1 GET Comments Events Service](#3101-get-comments-events-service) + + [3.10.2 GET Comment Events Service](#3102-get-comment-events-service) @@ -147,7 +139,7 @@ options available to the user for choice fields such as topic status. The client can calculate the available set of actions for a particular entity by taking the project-wide defaults from the project extensions, then replacing any keys defined in the entity's `authorization` map with the values specified locally. The meaning of each of the authorization keys is outlined in -[4.1.5 Expressing User Authorization through Project Extensions](#415-expressing-user-authorization-through-project-extensions). +[3.1.5 Expressing User Authorization through Project Extensions](#315-expressing-user-authorization-through-project-extensions). **Example Scenario (Topic)** @@ -208,178 +200,14 @@ BCF and model server are co-located on the same hosts. ![Topology3](Images/Topology3.png) ---------- -# 3. Public Services -## 3.1 Versions Service +# 3. BCF Services -[versions_GET.json](Schemas_draft-03/Public/versions_GET.json) - -**Resource URL (public resource)** - - GET /bcf/versions - -**Parameters** - -|Parameter|Type|Description|Required| -|---------|----|-----------|--------| -|version_id|string|Identifier of the version|true| -|detailed_version|string|Url to specification on GitHub|false| - -Returns a list of all supported BCF API versions of the server. - -**Example Request** - - GET /bcf/versions - -**Example Response** - - Response Code: 200 - OK - Body: - { - "versions": [{ - "version_id": "1.0", - "detailed_version": "https://github.com/BuildingSMART/BCF-API" - }, { - "version_id": "2.1", - "detailed_version": "https://github.com/BuildingSMART/BCF-API" - }] - } - ----------- - -## 3.2 Authentication Services - -### 3.2.1 Obtaining Authentication Information - -[auth_GET.json](Schemas_draft-03/Authentication/auth_GET.json) - -Authentication is based on the [OAuth 2.0 Protocol](http://tools.ietf.org/html/draft-ietf-oauth-v2-22). - -**Resource URL (public resource)** - - GET /bcf/{version}/auth - -**Parameters** - -|Parameter|Type|Description|Required| -|---------|----|-----------|--------| -|oauth2_auth_url|string|URL to authorization page (used for Authorization Code Grant and Implicit Grant OAuth2 flows)|false| -|oauth2_token_url|string|URL for token requests|false| -|oauth2_dynamic_client_reg_url|string|URL for automated client registration|false| -|http_basic_supported|boolean|Indicates if Http Basic Authentication is supported|false| -|supported_oauth2_flows|string[]|array of supported OAuth2 flows| - -If `oauth2_auth_url` is present, then `oauth2_token_url` must also be present and vice versa. If properties are not present in the response, clients should assume that the functionality is not supported by the server, e.g. a missing `http_basic_supported` property would indicate that Http basic authentication is not available on the server. - -OAuth2 flows are described in detail in the [OAuth2 specification](https://tools.ietf.org/html/rfc6749). BCF API servers may support the following workflows: -* `authorization_code_grant` - [4.1 - Authorization Code Grant](https://tools.ietf.org/html/rfc6749#section-4.1) -* `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) - -The [OAuth2 Client Credentials Grant (section 4.4)](https://tools.ietf.org/html/rfc6749#section-4.4) is not supported since it does not contain any user identity. -Also the [Extension Grants (section 4.5)](https://tools.ietf.org/html/rfc6749#section-4.5) are not supported. - -**Example Request** - - GET /bcf/2.1/auth - -**Example Response** - - Response Code: 200 - OK - Body: - { - "oauth2_auth_url": "https://example.com/bcf/oauth2/auth", - "oauth2_token_url": "https://example.com/bcf/oauth2/token", - "oauth2_dynamic_client_reg_url": "https://example.com/bcf/oauth2/reg", - "http_basic_supported": true, - "supported_oauth2_flows": [ - "authorization_code_grant", - "implicit_grant", - "resource_owner_password_credentials_grant" - ] - } - -### 3.2.2 OAuth2 Example - -An example for the OAuth2 Authorization Grant workflow [can be found here](OAuth2Examples.md). - -### 3.2.3 OAuth2 Protocol Flow - Dynamic Client Registration - -[dynRegClient\_POST.json](Schemas_draft-03/Authentication/dynRegClient_POST.json) - -[dynRegClient\_GET.json](Schemas_draft-03/Authentication/dynRegClient_GET.json) - -The following part describes the optional dynamic registration process of a client. BCF-Servers may offer additional processes registering clients, for example allowing a client application developer to register his client on the servers website. - -The resource url for this service is server specific and is returned as `oauth2_dynamic_client_reg_url` in the `GET /bcf/{version}/auth` resource. - -Register a new client : - -**Parameters** - -JSON encoded body using the `application/json` content type. - -|parameter|type|description| -|---------|----|-----------| -|client_name|string (max. length 60)|The client name| -|client_description|string (max. length 4000)|The client description| -|client_url|string|An URL providing additional information about the client| -|redirect_url|string|An URL where users are redirected after granting access to the client| - -**Example Request** - - POST https://example.com/bcf/oauth2/reg - Body: - { - "client_name": "Example Application", - "client_description": "Example CAD desktop application", - "client_url": "http://example.com", - "redirect_url": "http://localhost:8080" - } - -**Example Response** - - Response Code: 201 - Created - Body: - { - "client_id": "cGxlYXN1cmUu", - "client_secret": "ZWFzdXJlLg==" - } - ----------- - -## 3.3 User Services - -### 3.3.1 Get current user - -[user_GET.json](Schemas_draft-03/User/user_GET.json) - -**Resource URL** - - GET /bcf/{version}/current-user - -**Example Request** - - GET /bcf/2.1/current-user - -**Example Response** - - Response Code: 200 - OK - Body: - { - "id": "Architect@example.com", - "name": "John Doe" - } - ----------- - -# 4. BCF Services - -## 4.1 Project Services +## 3.1 Project Services For compatibility with the project structure of existing systems, the `project_id` property of `project` resources is **not forced to be a guid but may be any string**. -### 4.1.1 GET Projects Service +### 3.1.1 GET Projects Service **Resource URL** @@ -414,7 +242,7 @@ Retrieve a **collection** of projects where the currently logged on user has acc } }] -### 4.1.2 GET Project Service +### 3.1.2 GET Project Service **Resource URL** @@ -442,7 +270,7 @@ Retrieve a specific project. } } -### 4.1.3 PUT Project Service +### 3.1.3 PUT Project Service **Resource URL** @@ -450,7 +278,7 @@ Retrieve a specific project. [project_PUT.json](Schemas_draft-03/Project/project_PUT.json) -Modify a specific project. This operation is only possible when the server returns the `update` flag in the Project authorization, see section [4.1.5](#415-expressing-user-authorization-through-project-extensions) +Modify a specific project. This operation is only possible when the server returns the `update` flag in the Project authorization, see section [3.1.5](#315-expressing-user-authorization-through-project-extensions) **Example Request** @@ -474,7 +302,7 @@ Modify a specific project. This operation is only possible when the server retur } } -### 4.1.4 GET Project Extension Service +### 3.1.4 GET Project Extension Service **Resource URL** @@ -546,46 +374,46 @@ Project extensions are used to define possible values that can be used in topics ] } -### 4.1.5 Expressing User Authorization Through Project Extensions +### 3.1.5 Expressing User Authorization Through Project Extensions Global default authorizations for the requesting user can be expressed in the project schema. The actions authorized here will apply to any entities that do not override them locally. The complete set of options for the BCF entities are listed below. -#### 4.1.5.1 Project +#### 3.1.5.1 Project The 'project_actions' entry in the project extensions defines what actions are allowed to be performed at the project level. The available actions include: -* *update* - The ability to update the project details (see [4.1.3 PUT Project Service](#413-put-project-service)) -* *createTopic* - The ability to create a new topic (see [4.2.2 POST Topic Service](#422-post-topic-service)) -* *createDocument* - The ability to create a new document (see [4.8.2 POST Document Service](#492-post-document-service)) +* *update* - The ability to update the project details (see [3.1.3 PUT Project Service](#313-put-project-service)) +* *createTopic* - The ability to create a new topic (see [3.2.2 POST Topic Service](#322-post-topic-service)) +* *createDocument* - The ability to create a new document (see [3.8.2 POST Document Service](#382-post-document-service)) -#### 4.1.5.2 Topic +#### 3.1.5.2 Topic The 'topic_actions' entry in the project extensions defines what actions are allowed to be performed at the topic level by default (i.e. unless overridden by specific topics) The available actions include: -* *update* - The ability to update the topic (see [4.2.4 PUT Topic Service](#424-put-topic-service)) -* *updateBimSnippet* - The ability to update the BIM snippet for topics (see [4.2.7 PUT Topic BIM Snippet Service](#427-put-topic-bim-snippet-service)) -* *updateRelatedTopics* - The ability to update the collection of related topics (see [4.6.2 PUT Related Topics Service](#472-put-related-topics-service)) -* *updateDocumentReferences* - The ability to update the collection of document references (see [4.7.3 PUT Document Reference Service](#483-put-document-reference-service)) -* *updateFiles* - The ability to update the file header (see [4.3.2 PUT Files (Header) Service](#432-put-files-header-service)) -* *createComment* - The ability to create a comment (see [4.4.2 POST Comment Service](#442-post-comment-service)) -* *createViewpoint* - The ability to create a new viewpoint (see [4.5.2 POST Viewpoint Service](#452-post-viewpoint-service)) +* *update* - The ability to update the topic (see [3.2.4 PUT Topic Service](#324-put-topic-service)) +* *updateBimSnippet* - The ability to update the BIM snippet for topics (see [3.2.7 PUT Topic BIM Snippet Service](#327-put-topic-bim-snippet-service)) +* *updateRelatedTopics* - The ability to update the collection of related topics (see [3.6.2 PUT Related Topics Service](#362-put-related-topics-service)) +* *updateDocumentReferences* - The ability to update the collection of document references (see [3.7.3 PUT Document Reference Service](#373-put-document-reference-service)) +* *updateFiles* - The ability to update the file header (see [3.3.3 PUT Files (Header) Service](#333-put-files-header-service)) +* *createComment* - The ability to create a comment (see [3.4.2 POST Comment Service](#342-post-comment-service)) +* *createViewpoint* - The ability to create a new viewpoint (see [3.5.2 POST Viewpoint Service](#352-post-viewpoint-service)) -#### 4.1.5.3 Comment +#### 3.1.5.3 Comment The 'comment_actions' entry in the project extensions defines what actions are allowed to be performed at the comment level by default (i.e unless overridden by specific comments). The available actions include: -* *update* - The ability to update the comment (see [4.4.4 PUT Comment Service](#444-put-comment-service)) +* *update* - The ability to update the comment (see [3.4.4 PUT Comment Service](#344-put-comment-service)) --------- -## 4.2 Topic Services +## 3.2 Topic Services -### 4.2.1 GET Topics Service +### 3.2.1 GET Topics Service **Resource URL** @@ -616,7 +444,7 @@ Retrieve a **collection** of topics related to a project (default sort order is |---------|-----------| |creation_date|creation date of a topic| |modified_date|modification date of a topic| -|server_id|the [server_id](#429-topic-identifiers) of the topic| +|server_id|the [server_id](#329-topic-identifiers) of the topic| |index|index of a topic| **Example Request with odata** @@ -661,7 +489,7 @@ Get topics that have at least one of the labels 'Architecture', 'Structural' or "creation_date": "2014-11-19T14:24:11.316Z" }] -### 4.2.2 POST Topic Service +### 3.2.2 POST Topic Service **Resource URL** @@ -669,7 +497,7 @@ Get topics that have at least one of the labels 'Architecture', 'Structural' or [topic_POST.json](Schemas_draft-03/Collaboration/Topic/topic_POST.json) -Add a new topic. This operation is only possible when the server returns the `createTopic` flag in the Project authorization, see section [4.1.5](#415-expressing-user-authorization-through-project-extensions) +Add a new topic. This operation is only possible when the server returns the `createTopic` flag in the Project authorization, see section [3.1.5](#315-expressing-user-authorization-through-project-extensions) **Parameters** @@ -744,7 +572,7 @@ _Note: If "bim_snippet" is present, then all four properties (`snippet_type`, `i } } -### 4.2.3 GET Topic Service +### 3.2.3 GET Topic Service **Resource URL** @@ -790,7 +618,7 @@ Retrieve a specific topic. } } -### 4.2.4 PUT Topic Service +### 3.2.4 PUT Topic Service **Resource URL** @@ -798,7 +626,7 @@ Retrieve a specific topic. [topic_PUT.json](Schemas_draft-03/Collaboration/Topic/topic_PUT.json) -Modify a specific topic, description similar to POST. This operation is only possible when the server returns the `update` flag in the Topic authorization, see section [4.2.8](#428-determining-allowed-topic-modifications) +Modify a specific topic, description similar to POST. This operation is only possible when the server returns the `update` flag in the Topic authorization, see section [3.2.8](#328-determining-allowed-topic-modifications) **Example Request** @@ -850,13 +678,13 @@ Modify a specific topic, description similar to POST. This operation is only pos } } -### 4.2.5 DELETE Topic Service +### 3.2.5 DELETE Topic Service **Resource URL** DELETE /bcf/{version}/projects/{project_id}/topics/{guid} -Deletes a single topic. This operation is only possible when the server returns the `delete` flag in the Topic authorization, see section [4.2.8](#428-determining-allowed-topic-modifications) +Deletes a single topic. This operation is only possible when the server returns the `delete` flag in the Topic authorization, see section [3.2.8](#328-determining-allowed-topic-modifications) **Example Request** @@ -866,7 +694,7 @@ Deletes a single topic. This operation is only possible when the server returns Response Code: 200 - OK -### 4.2.6 GET Topic BIM Snippet Service +### 3.2.6 GET Topic BIM Snippet Service **Resource URL** @@ -874,21 +702,21 @@ Deletes a single topic. This operation is only possible when the server returns Retrieves a topics BIM-Snippet as binary file. -### 4.2.7 PUT Topic BIM Snippet Service +### 3.2.7 PUT Topic BIM Snippet Service **Resource URL** PUT /bcf/{version}/projects/{project_id}/topics/{guid}/snippet -Puts a new BIM Snippet binary file to a topic. If this is used, the parent topics BIM Snippet property `is_external` must be set to `false` and the `reference` must be the file name with extension. This operation is only possible when the server returns the `updateBimSnippet` flag in the Topic authorization, see section [4.2.8](#428-determining-allowed-topic-modifications) +Puts a new BIM Snippet binary file to a topic. If this is used, the parent topics BIM Snippet property `is_external` must be set to `false` and the `reference` must be the file name with extension. This operation is only possible when the server returns the `updateBimSnippet` flag in the Topic authorization, see section [3.2.8](#328-determining-allowed-topic-modifications) -### 4.2.8 Determining Allowed Topic Modifications +### 3.2.8 Determining Allowed Topic Modifications The global default Topic authorizations are expressed in the project schema and when Topic(s) are requested with the query parameter "includeAuthorization" equal to "true" Topics will include an "authorization" field containing any local overrides for each Topic. -### 4.2.9 Topic Identifiers +### 3.2.9 Topic Identifiers Each topic has two identifiers: 1. `guid` - machine-friendly, randomly generated and universally unique identifier. Both clients and servers must generate @@ -903,9 +731,9 @@ Each topic has two identifiers: `server_id` examples: 003490, ISSUE-01, CLASH-578 -## 4.3 File Services +## 3.3 File Services -### 4.3.1 GET Project Files Information Service +### 3.3.1 GET Project Files Information Service **Resource URL** @@ -969,7 +797,7 @@ user choose to associate a topic with that `File`. }] -### 4.3.2 GET Files (Header) Service +### 3.3.2 GET Files (Header) Service **Resource URL** @@ -1001,7 +829,7 @@ Retrieve a **collection** of file references as topic header. > Note: In the above example, the second items reference is in a guid format and points to a model file that is located on the server. Servers don't have to use guid formats for their internal ids, so the expected format of the response can vary between servers. -### 4.3.3 PUT Files (Header) Service +### 3.3.3 PUT Files (Header) Service **Resource URL** @@ -1009,7 +837,7 @@ Retrieve a **collection** of file references as topic header. [file_PUT.json](Schemas_draft-03/Collaboration/File/file_PUT.json) -Update a **collection** of file references on the topic header. This operation is only possible when the server returns the `updateFiles` flag in the Topic authorization, see section [4.2.8](#428-determining-allowed-topic-modifications) +Update a **collection** of file references on the topic header. This operation is only possible when the server returns the `updateFiles` flag in the Topic authorization, see section [3.2.8](#328-determining-allowed-topic-modifications) **Example Request** @@ -1039,9 +867,9 @@ Update a **collection** of file references on the topic header. This operation i "reference": "https://example.com/files/3hwBHP91jBRwPsmyf$3Hea_0003.ifc" }] -## 4.4 Comment Services +## 3.4 Comment Services -### 4.4.1 GET Comments Service +### 3.4.1 GET Comments Service **Resource URL** @@ -1097,7 +925,7 @@ Get comments that are created after December 5 2015. Sort the result on first cr "topic_guid": "B345F4F2-3A04-B43B-A713-5E456BEF8228" }] -### 4.4.2 POST Comment Service +### 3.4.2 POST Comment Service **Resource URL** @@ -1105,7 +933,7 @@ Get comments that are created after December 5 2015. Sort the result on first cr [comment_POST.json](Schemas_draft-03/Collaboration/Comment/comment_POST.json) -Add a new comment to a topic. This operation is only possible when the server returns the `createComment` flag in the Topic authorization, see section [4.2.8](#428-determining-allowed-topic-modifications) +Add a new comment to a topic. This operation is only possible when the server returns the `createComment` flag in the Topic authorization, see section [3.2.8](#328-determining-allowed-topic-modifications) **Parameters** @@ -1138,7 +966,7 @@ JSON encoded body using the "application/json" content type. "topic_guid": "B345F4F2-3A04-B43B-A713-5E456BEF8228" } -### 4.4.3 GET Comment Service +### 3.4.3 GET Comment Service **Resource URL** @@ -1164,7 +992,7 @@ Get a single comment. "topic_guid": "B345F4F2-3A04-B43B-A713-5E456BEF8228" } -### 4.4.4 PUT Comment Service +### 3.4.4 PUT Comment Service **Resource URL** @@ -1172,7 +1000,7 @@ Get a single comment. [comment_PUT.json](Schemas_draft-03/Collaboration/Comment/comment_PUT.json) -Update a single comment, description similar to POST. This operation is only possible when the server returns the `update` flag in the Comment authorization, see section [4.4.6](#446-determining-allowed-comment-modifications) +Update a single comment, description similar to POST. This operation is only possible when the server returns the `update` flag in the Comment authorization, see section [3.4.6](#346-determining-allowed-comment-modifications) **Example Request** @@ -1196,13 +1024,13 @@ Update a single comment, description similar to POST. This operation is only pos "topic_guid": "B345F4F2-3A04-B43B-A713-5E456BEF8228" } -### 4.4.5 DELETE Comment Service +### 3.4.5 DELETE Comment Service **Resource URL** DELETE /bcf/{version}/projects/{project_id}/topics/{guid}/comments/{guid} -Deletes a single comment. This operation is only possible when the server returns the `delete` flag in the Comment authorization, see section [4.4.6](#446-determining-allowed-comment-modifications) +Deletes a single comment. This operation is only possible when the server returns the `delete` flag in the Comment authorization, see section [3.4.6](#346-determining-allowed-comment-modifications) **Example Request** @@ -1212,15 +1040,15 @@ Deletes a single comment. This operation is only possible when the server return Response Code: 200 - OK -### 4.4.6 Determining allowed Comment modifications +### 3.4.6 Determining allowed Comment modifications The global default Comment authorizations are expressed in the project schema and when Comment(s) are requested with the query parameter "includeAuthorization" equal to "true" Comments will include an "authorization" field containing any local overrides for each Comment. -## 4.5 Viewpoint Services +## 3.5 Viewpoint Services -### 4.5.1 GET Viewpoints Service +### 3.5.1 GET Viewpoints Service **Resource URL** @@ -1328,7 +1156,7 @@ Retrieve a **collection** of all viewpoints related to a topic. }] }] -### 4.5.2 POST Viewpoint Service +### 3.5.2 POST Viewpoint Service **Resource URL** @@ -1336,7 +1164,7 @@ Retrieve a **collection** of all viewpoints related to a topic. [viewpoint_POST.json](Schemas_draft-03/Collaboration/Viewpoint/viewpoint_POST.json) -Add a new viewpoint. Viewpoints are immutable, meaning that they should never change. Requirements for different visualizations should be handled by creating new viewpoint elements. This operation is only possible when the server returns the `createViewpoint` flag in the Topic authorization, see section [4.2.8](#428-determining-allowed-topic-modifications) +Add a new viewpoint. Viewpoints are immutable, meaning that they should never change. Requirements for different visualizations should be handled by creating new viewpoint elements. This operation is only possible when the server returns the `createViewpoint` flag in the Topic authorization, see section [3.2.8](#328-determining-allowed-topic-modifications) **Parameters** @@ -1346,15 +1174,15 @@ JSON encoded body using the "application/json" content type. |---------|----|-----------|--------| | guid | string | The desired guid | optional | | index | integer | parameter for sorting | optional | -| orthogonal camera | [Orthogonal camera](#4523-orthogonal-camera) | orthogonal camera view | optional | -| perspective camera | [Perspective camera](#4524-perspective-camera) | perspective view of the camera | optional | -| lines | array of [Line](#4525-line) | graphical line | optional | -| clipping_planes | array of [Clipping Plane](#4526-clipping-plane) | clipping planes for the model view | optional | -| bitmaps | array of [Bitmap](#4527-bitmap) | embedded pictures in the viewpoint | optional | -| snapshot | [Snapshot](#4528-snapshot) | snapshot image of the viewpoint | optional | -| components | [Components](#4529-components) | Components in the viewpoint | optional | - -#### 4.5.2.1 Point +| orthogonal camera | [Orthogonal camera](#3523-orthogonal-camera) | orthogonal camera view | optional | +| perspective camera | [Perspective camera](#3524-perspective-camera) | perspective view of the camera | optional | +| lines | array of [Line](#3525-line) | graphical line | optional | +| clipping_planes | array of [Clipping Plane](#3526-clipping-plane) | clipping planes for the model view | optional | +| bitmaps | array of [Bitmap](#3527-bitmap) | embedded pictures in the viewpoint | optional | +| snapshot | [Snapshot](#3528-snapshot) | snapshot image of the viewpoint | optional | +| components | [Components](#3529-components) | Components in the viewpoint | optional | + +#### 3.5.2.1 Point [point.json](Schemas_draft-03/Collaboration/Viewpoint/point.json) |parameter|type|description|required| @@ -1363,7 +1191,7 @@ JSON encoded body using the "application/json" content type. | y | number | y point | mandatory | | z | number | z point | mandatory | -#### 4.5.2.2 Direction +#### 3.5.2.2 Direction [direction.json](Schemas_draft-03/Collaboration/Viewpoint/direction.json) Direction must not be a zero vector. @@ -1374,55 +1202,55 @@ Direction must not be a zero vector. | y | number | y direction | mandatory | | z | number | z direction | mandatory | -#### 4.5.2.3 Orthogonal camera +#### 3.5.2.3 Orthogonal camera [orthogonal_camera.json](Schemas_draft-03/Collaboration/Viewpoint/orthogonal_camera.json) |parameter|type|description|required| |---------|----|-----------|--------| -| camera_view_point | [Direction](#4522-direction) | viewpoint of the camera | mandatory | -| camera_direction | [Direction](#4522-direction) | direction of the camera | mandatory | -| camera_up_vector | [Direction](#4522-direction) | direction of camera up | mandatory | +| camera_view_point | [Direction](#3522-direction) | viewpoint of the camera | mandatory | +| camera_direction | [Direction](#3522-direction) | direction of the camera | mandatory | +| camera_up_vector | [Direction](#3522-direction) | direction of camera up | mandatory | | view_to_world_scale | number | proportion of camera view to model | mandatory | -#### 4.5.2.4 Perspective camera +#### 3.5.2.4 Perspective camera [perspective_camera.json](Schemas_draft-03/Collaboration/Viewpoint/perspective_camera.json) |parameter|type|description|required| |---------|----|-----------|--------| -| camera_view_point | [Point](#4521-point) | viewpoint of the camera | mandatory | -| camera_direction | [Direction](#4522-direction) | direction of the camera | mandatory | -| camera_up_vector | [Direction](#4522-direction) | direction of camera up | mandatory | +| camera_view_point | [Point](#3521-point) | viewpoint of the camera | mandatory | +| camera_direction | [Direction](#3522-direction) | direction of the camera | mandatory | +| camera_up_vector | [Direction](#3522-direction) | direction of camera up | mandatory | | field_of_view | number | field of view | mandatory | -#### 4.5.2.5 Line +#### 3.5.2.5 Line [line.json](Schemas_draft-03/Collaboration/Viewpoint/line.json) |parameter|type|description|required| |---------|----|-----------|--------| -| start_point | [Point](#4521-point) | start point of the line | mandatory | -| end_point | [Point](#4521-point) | end point of the line (Treated as point if start_point and end_point is the same | mandatory | +| start_point | [Point](#3521-point) | start point of the line | mandatory | +| end_point | [Point](#3521-point) | end point of the line (Treated as point if start_point and end_point is the same | mandatory | -#### 4.5.2.6 Clipping plane +#### 3.5.2.6 Clipping plane [clipping_plane.json](Schemas_draft-03/Collaboration/Viewpoint/clipping_plane.json) |parameter|type|description|required| |---------|----|-----------|--------| -| location | [Point](#4521-point) | origin of the clipping plane | mandatory | -| direction | [Direction](#4522-direction) | direction of the clipping plane | mandatory | +| location | [Point](#3521-point) | origin of the clipping plane | mandatory | +| direction | [Direction](#3522-direction) | direction of the clipping plane | mandatory | -#### 4.5.2.7 Bitmap +#### 3.5.2.7 Bitmap [bitmap.json](Schemas_draft-03/Collaboration/Viewpoint/bitmap_POST.json) |parameter|type|description|required| |---------|----|-----------|--------| | bitmap_type | enum (string) | format of the bitmap. Predefined values `png` or `jpg` | mandatory | | bitmap_data | base64 encoded string | The bitmap image data | mandatory | -| location | [Point](#4521-point) | location of the center of the bitmap in world coordinates (point) | mandatory | -| normal | [Direction](#4522-direction) | normal vector of the bitmap (vector) | mandatory | -| up | [Direction](#4522-direction) | up vector of the bitmap (vector) | mandatory | +| location | [Point](#3521-point) | location of the center of the bitmap in world coordinates (point) | mandatory | +| normal | [Direction](#3522-direction) | normal vector of the bitmap (vector) | mandatory | +| up | [Direction](#3522-direction) | up vector of the bitmap (vector) | mandatory | | height | number | height of bitmap in the scene | mandatory | -#### 4.5.2.8 Snapshot +#### 3.5.2.8 Snapshot [snapshot.json](Schemas_draft-03/Collaboration/Viewpoint/snapshot_POST.json) |parameter|type|description|required| @@ -1430,16 +1258,16 @@ Direction must not be a zero vector. | snapshot_type | enum (string) | format of the snapshot. Predefined values `png` or `jpg` | mandatory | | snapshot_data | base64 encoded string | The snapshot image data | mandatory | -#### 4.5.2.9 Components +#### 3.5.2.9 Components [components.json](Schemas_draft-03/Collaboration/Viewpoint/components.json) |parameter|type|description|required| |---------|----|-----------|--------| -| selection | array of [Component](#45210-component) | Selected components | optional | -| coloring | array of [Coloring](#45211-coloring) | Colored components | optional | -| visibility | [Visibility](#45212-visibility) | Visibility of components | mandatory | +| selection | array of [Component](#35210-component) | Selected components | optional | +| coloring | array of [Coloring](#35211-coloring) | Colored components | optional | +| visibility | [Visibility](#35212-visibility) | Visibility of components | mandatory | -#### 4.5.2.10 Component +#### 3.5.2.10 Component [component.json](Schemas_draft-03/Collaboration/Viewpoint/component.json) ##### Optimization rules @@ -1452,7 +1280,7 @@ BCF is suitable for selecting a few components. A huge list of selected componen | originating_system | string | originating system of the component | optional | | authoring_tool_id | string | internal id for the authoring tool of the component | optional | -#### 4.5.2.11 Coloring +#### 3.5.2.11 Coloring [coloring.json](Schemas_draft-03/Collaboration/Viewpoint/coloring.json) ##### Optimization rules @@ -1464,9 +1292,9 @@ The color is given in ARGB format. Colors are represented as 6 or 8 hexadecimal |parameter|type|description|required| |---------|----|-----------|--------| | color | string | Color of the components | mandatory | -| components | array of [Component](#45210-component) | Colored components | mandatory | +| components | array of [Component](#35210-component) | Colored components | mandatory | -#### 4.5.2.12 Visibility +#### 3.5.2.12 Visibility [visibility.json](Schemas_draft-03/Collaboration/Viewpoint/visibility.json) ##### Optimization rules @@ -1478,10 +1306,10 @@ BCF is suitable for hiding/showing a few components. A huge list of hidden/shown |parameter|type|description|required| |---------|----|-----------|--------| | default_visibility | boolean | If true: Show all components, and hide the exceptions. If false: Hide all components and show exceptions | optional, default false | -| exceptions | array of [Component](#45210-component) | Components to hide/show determined by default_visibility | optional | -| view_setup_hints | [View setup hints](#45213-view-setup-hints) | Hints about the setup of the viewer | optional | +| exceptions | array of [Component](#35210-component) | Components to hide/show determined by default_visibility | optional | +| view_setup_hints | [View setup hints](#35213-view-setup-hints) | Hints about the setup of the viewer | optional | -#### 4.5.2.13 View setup hints +#### 3.5.2.13 View setup hints [view_setup_hints.json](Schemas_draft-03/Collaboration/Viewpoint/view_setup_hints.json) |parameter|type|description|required| @@ -1661,7 +1489,7 @@ BCF is suitable for hiding/showing a few components. A huge list of hidden/shown "snapshot_type": "png" } } -### 4.5.3 GET Viewpoint Service +### 3.5.3 GET Viewpoint Service **Resource URL** @@ -1749,7 +1577,7 @@ Retrieve a specific viewpoint. } } -### 4.5.4 GET Viewpoint Snapshot Service +### 3.5.4 GET Viewpoint Snapshot Service **Resource URL** @@ -1761,7 +1589,7 @@ Retrieve a viewpoints snapshot (png or jpg) as image file. A viewpoint contains GET /bcf/2.1/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/viewpoints/a11a82e7-e66c-34b4-ada1-5846abf39133/snapshot -### 4.5.5 GET Viewpoint Bitmap Service +### 3.5.5 GET Viewpoint Bitmap Service **Resource URL** @@ -1773,7 +1601,7 @@ Retrieve a specific viewpoints bitmap image file (png or jpg). GET /bcf/2.1/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/viewpoints/a11a82e7-e66c-34b4-ada1-5846abf39133/bitmaps/20c1cb56-315f-4a0a-922d-ed7a4a8edf55 -### 4.5.6 GET selected Components Service +### 3.5.6 GET selected Components Service **Resource URL** GET /bcf/{version}/projects/{project_id}/topics/{guid}/viewpoints/{guid}/selection @@ -1802,7 +1630,7 @@ Retrieve a **collection** of all selected components in a viewpoint. ] } -### 4.5.7 GET colored Components Service +### 3.5.7 GET colored Components Service **Resource URL** @@ -1837,7 +1665,7 @@ Retrieve a **collection** of all colored components in a viewpoint. ] } -### 4.5.8 GET visibility of Components Service +### 3.5.8 GET visibility of Components Service **Resource URL** @@ -1875,13 +1703,13 @@ Retrieve visibility of components in a viewpoint. } } -### 4.5.9 DELETE Viewpoint Service +### 3.5.9 DELETE Viewpoint Service **Resource URL** DELETE /bcf/{version}/projects/{project_id}/topics/{guid}/viewpoints/{guid} -Deletes a single viewpoint. This operation is only possible when the server returns the `delete` flag in the Viewpoint authorization, see section [4.5.10](#4510-determining-allowed-viewpoint-modifications) +Deletes a single viewpoint. This operation is only possible when the server returns the `delete` flag in the Viewpoint authorization, see section [3.5.10](#3510-determining-allowed-viewpoint-modifications) **Example Request** @@ -1891,15 +1719,15 @@ Deletes a single viewpoint. This operation is only possible when the server retu Response Code: 200 - OK -### 4.5.10 Determining allowed Viewpoint modifications +### 3.5.10 Determining allowed Viewpoint modifications The global default Viewpoint authorizations are expressed in the project schema and when Viewpoint(s) are requested with the query parameter "includeAuthorization" equal to "true" Viewpoints will include an "authorization" field containing any local overrides for each Viewpoint. -## 4.6 Related Topics Services +## 3.6 Related Topics Services -### 4.6.1 GET Related Topics Service +### 3.6.1 GET Related Topics Service **Resource URL** @@ -1923,7 +1751,7 @@ Retrieve a **collection** of all related topics to a topic. "related_topic_guid": "6963a846-54d1-4050-954d-607cd5e48aa3" }] -### 4.6.2 PUT Related Topics Service +### 3.6.2 PUT Related Topics Service **Resource URL** @@ -1931,7 +1759,7 @@ Retrieve a **collection** of all related topics to a topic. [related_topic_PUT.json](Schemas_draft-03/Collaboration/RelatedTopic/related_topic_PUT.json) -Add or update a **collection** of all related topics to a topic. This operation is only possible when the server returns the `updateRelatedTopics` flag in the Topic authorization, see section [4.2.8](#428-determining-allowed-topic-modifications) +Add or update a **collection** of all related topics to a topic. This operation is only possible when the server returns the `updateRelatedTopics` flag in the Topic authorization, see section [3.2.8](#328-determining-allowed-topic-modifications) **Example Request** @@ -1957,16 +1785,16 @@ Add or update a **collection** of all related topics to a topic. This operation "related_topic_guid": "bac66ab4-331e-4f21-a28e-083d2cf2e796" }] -## 4.7 Document Reference Services +## 3.7 Document Reference Services Service for relating documents to topics. Related documents can be either internal or external, determined by the fields **url** and **document_guid**. The **url** and the **document_guid** fields are mutually exclusive, which means that only one of these fields are set. A document_reference with **url** set, is referencing an external resource. -A document_reference with **document_guid** set, is referencing an internal **document** which can be downloaded using the [GET Document Service](#483-get-document-service). +A document_reference with **document_guid** set, is referencing an internal **document** which can be downloaded using the [GET Document Service](#383-get-document-service). -### 4.7.1 GET Document References Service +### 3.7.1 GET Document References Service **Resource URL** @@ -1994,7 +1822,7 @@ Retrieve a **collection** of all document references to a topic. "description": "The building owners global design parameters for buildings." }] -### 4.7.2 POST Document Reference Service +### 3.7.2 POST Document Reference Service **Resource URL** @@ -2002,7 +1830,7 @@ Retrieve a **collection** of all document references to a topic. [document_reference_POST.json](Schemas_draft-03/Collaboration/DocumentReference/document_reference_POST.json) -Add a document reference to a topic. This operation is only possible when the server returns the `updateDocumentReferences` flag in the Topic authorization, see section [4.2.8](#428-determining-allowed-topic-modifications) +Add a document reference to a topic. This operation is only possible when the server returns the `updateDocumentReferences` flag in the Topic authorization, see section [3.2.8](#328-determining-allowed-topic-modifications) Should either reference an internal or an external document. - Internal @@ -2061,7 +1889,7 @@ JSON encoded body using the "application/json" content type. "description": "The building owners global design parameters for buildings." } -### 4.7.3 PUT Document Reference Service +### 3.7.3 PUT Document Reference Service **Resource URL** @@ -2070,7 +1898,7 @@ JSON encoded body using the "application/json" content type. [document_reference_PUT.json](Schemas_draft-03/Collaboration/DocumentReference/document_reference_PUT.json) Update an existing document reference identified by **guid**. -Uses the same rules as [POST Document Reference Service](#472-post-document-reference-service). This operation is only possible when the server returns the `updateDocumentReferences` flag in the Topic authorization, see section [4.2.8](#428-determining-allowed-topic-modifications) +Uses the same rules as [POST Document Reference Service](#372-post-document-reference-service). This operation is only possible when the server returns the `updateDocumentReferences` flag in the Topic authorization, see section [3.2.8](#328-determining-allowed-topic-modifications) **Example Request** @@ -2091,9 +1919,9 @@ Uses the same rules as [POST Document Reference Service](#472-post-document-refe "description": "The legal requirements for buildings." } -## 4.8 Document Services +## 3.8 Document Services -### 4.8.1 GET Documents Service +### 3.8.1 GET Documents Service [document_GET.json](Schemas_draft-03/Collaboration/Document/document_GET.json) @@ -2119,13 +1947,13 @@ Retrieve a **collection** of all documents uploaded to a project. "filename": "DesignParameters.pdf" }] -### 4.8.2 POST Document Service +### 3.8.2 POST Document Service **Resource URL** POST /bcf/{version}/projects/{project_id}/documents -Upload a document (binary file) to a project. This operation is only possible when the server returns the `createDocument` flag in the Project authorization, see section [4.1.5](#415-expressing-user-authorization-through-project-extensions) +Upload a document (binary file) to a project. This operation is only possible when the server returns the `createDocument` flag in the Project authorization, see section [3.1.5](#315-expressing-user-authorization-through-project-extensions) Optional: The desired document guid may be passed as a query parameter. @@ -2142,7 +1970,7 @@ Optional: The desired document guid may be passed as a query parameter. "filename": "Official_Building_Permission.pdf" } -### 4.8.3 GET Document Service +### 3.8.3 GET Document Service **Resource URL** @@ -2158,12 +1986,12 @@ Retrieves a document as binary file. Retrieves a document as binary file. -## 4.9 Topics Events Services +## 3.9 Topics Events Services The topic events service reflects the events for topics. Each creation or update of a topic generates new topic events. Note: Whenever a topic has been created, the server also generates "update" and "add" events for all fields that are initially set. Example: If a topic contains a description, the **description_updated** event is generated. This is to ensure the full history. -### 4.9.1 GET Topics Events Service +### 3.9.1 GET Topics Events Service **Resource URL** @@ -2254,7 +2082,7 @@ Get events that are of type 'status_updated', 'type_updated' or 'title_updated' ] }] -### 4.9.2 GET Topic Events Service +### 3.9.2 GET Topic Events Service **Resource URL** @@ -2345,13 +2173,13 @@ Get events that is of type 'status_updated', 'type_updated' or 'title_updated' o ] }] -## 4.10 Comments Events Services +## 3.10 Comments Events Services The comment events service reflects the events for topic comments. Each creation or update of a comment generates new comment events. Note: Whenever a comment has been created, the server also generates "update" events for all fields that are initially set. Example: If a comment contains a viewpoint, the **viewpoint_updated** event is generated. This is to ensure the full history. -### 4.10.1 GET Comments Events Service +### 3.10.1 GET Comments Events Service **Resource URL** @@ -2434,7 +2262,7 @@ Get events that are of type 'comment_created', or 'viewpoint_updated' ] }] -### 4.10.2 GET Comment Events Service +### 3.10.2 GET Comment Events Service **Resource URL**