Version 2.1 based on BCFv2.1. BCF XML GitHub repository
Version 1.0 of the BCF API specification is available here
Table of Contents
- 1. Introduction
- 2. Topologies
- 3. Public Services
- 4. BCF Services
- 4.1 Project Services
- 4.2 Topic Services
- 4.3 File Services
- 4.4 Comment Services
- 4.5 Viewpoint Services
- 4.5.1 GET Viewpoints Service
- 4.5.2 POST Viewpoint Service
- 4.5.3 GET Viewpoint Service
- 4.5.4 GET Viewpoint Snapshot Service
- 4.5.5 GET Viewpoint Bitmap Service
- 4.5.6 GET selected Components Service
- 4.5.7 GET colored Components Service
- 4.5.8 GET visibility of Components Service
- 4.6 Related Topics Services
- 4.7 Document Reference Services
- 4.8 Document Services
- 4.9 Topics Events Services
- 4.10 Comments Events Services
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 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.
An example of a client implementation in C# can be found here: https://github.com/rvestvik/BcfApiExampleClient
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/.
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.
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.
To work with browser based API clients using Cross Origin Resource Sharing (Cors), 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 theAuthorization
,Content-Type
andAccept
headers to be used via XHR requestsAccess-Control-Allow-Methods: GET, POST, PUT, OPTIONS
to allow the Http methods the API needsAccess-Control-Allow-Origin: example.com
to allow XHR requests from theexample.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.
<httpProtocol>
<customHeaders>
<add name="Access-Control-Allow-Headers" value="Content-Type, Accept, X-Requested-With, Authorization" />
<add name="Access-Control-Allow-Methods" value="GET, POST, PUT, DELETE, OPTIONS" />
<add name="Access-Control-Allow-Origin" value="*" />
</customHeaders>
</httpProtocol>
The BCF API relies on the regular Http Status Code definitions. Good sources are Wikipedia or the HTTP/1.1 Specification.
Generally, these response codes shall be used in the API:
200 - OK
forGET
requests that return data orPUT
requests that update data201 - Created
forPOST
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.
BCF-API has a specified error response body format error.json.
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
.
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.
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
authorization defaults for that entity. Using this information clients can decide whether to, for example, include an
"Edit" button in the UI displaying the entity depending on the actions permitted for the user.
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 outlined in
4.1.5 Expressing User Authorization through Project Extensions.
Example Scenario (Topic)
In the Project Extensions
{
"topic_actions": [],
"topic_status": [
"open",
"closed",
"confirmed"
]
}
Indicating that by default:
- no modifications can be made to Topics
- Topics can be placed in
open
,closed
orconfirmed
status
In the Topic
{
"authorization": {
"topic_actions": [
"update",
"createComment",
"createViewpoint"
],
"topic_status": [
"closed"
]
}
}
Indicating that for this topic, the current user can:
- update the Topic, or add comments or viewpoints
- place the Topic into
closed
status
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 produces errors on additional properties. Servers and clients are not required to preserve these properties.
Some endpoints in the BCF API expect binary file uploads, such as 4.8.2 POST Document Service or 4.2.7 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}";
Model collaboration is managed through a shared file server or a network file sharing service like Dropbox. The BCF-Server handles the authentication and the BCF-Issues.
BCF and model server are co-located on the same hosts.
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"
}]
}
Authentication is based on the OAuth 2.0 Protocol.
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. BCF API servers may support the following workflows:
authorization_code_grant
- 4.1 - Authorization Code Grantimplicit_grant
- 4.2 - Implicit Grantresource_owner_password_credentials_grant
- 4.3 - Resource Owner Password Credentials Grant
The OAuth2 Client Credentials Grant (section 4.4) is not supported since it does not contain any user identity. Also the Extension Grants (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"
]
}
An example for the OAuth2 Authorization Grant workflow can be found here.
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=="
}
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"
}
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.
Resource URL
GET /bcf/{version}/projects
Retrieve a collection of projects where the currently logged on user has access to.
Example Request
GET /bcf/2.1/projects
Example Response
Response Code: 200 - OK
Body:
[{
"project_id": "F445F4F2-4D02-4B2A-B612-5E456BEF9137",
"name": "Example project 1",
"authorization": {
"project_actions": [
"createTopic",
"createDocument"
]
}
}, {
"project_id": "A233FBB2-3A3B-EFF4-C123-DE22ABC8414",
"name": "Example project 2",
"authorization": {
"project_actions": []
}
}]
Resource URL
GET /bcf/{version}/projects/{project_id}
Retrieve a specific project.
Example Request
GET /bcf/2.1/projects/B724AAC3-5B2A-234A-D143-AE33CC18414
Example Response
Response Code: 200 - OK
Body:
{
"project_id": "B724AAC3-5B2A-234A-D143-AE33CC18414",
"name": "Example project 3",
"authorization": {
"project_actions": [
"update",
"updateProjectExtensions"
]
}
}
Resource URL
PUT /bcf/{version}/projects/{project_id}
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
Example Request
PUT /bcf/2.1/projects/B724AAC3-5B2A-234A-D143-AE33CC18414
Body:
{
"name": "Example project 3 - Second Section"
}
Example Response
Response Code: 200 - OK
Body:
{
"project_id": "B724AAC3-5B2A-234A-D143-AE33CC18414",
"name": "Example project 3 - Second Section",
"authorization": {
"project_actions": [
"update",
"updateProjectExtensions"
]
}
}
Resource URL
GET /bcf/{version}/projects/{project_id}/extensions
Retrieve a specific projects extensions. Project extensions are used to define possible values that can be used in topics and comments, for example topic labels and priorities. They may change during the course of a project. The most recent extensions state which values are valid at a given moment for newly created topics and comments.
Example Request
GET /bcf/2.1/projects/B724AAC3-5B2A-234A-D143-AE33CC18414/extensions
Example Response
Response Code: 200 - OK
Body:
{
"topic_type": [
"Information",
"Error"
],
"topic_status": [
"Open",
"Closed",
"ReOpened"
],
"topic_label": [
"Architecture",
"Structural",
"MEP"
],
"snippet_type": [
".ifc",
".csv"
],
"priority": [
"Low",
"Medium",
"High"
],
"user_id_type": [
"Architect@example.com",
"BIM-Manager@example.com",
"bob_heater@example.com"
],
"stage": [
"Preliminary Planning End",
"Construction Start",
"Construction End"
],
"project_actions": [
"update",
"createTopic",
"createDocument",
"updateProjectExtensions"
],
"topic_actions": [
"update",
"updateBimSnippet",
"updateRelatedTopics",
"updateDocumentReferences",
"updateFiles",
"createComment",
"createViewpoint"
],
"comment_actions": [
"update"
]
}
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.
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)
- createTopic - The ability to create a new topic (see 4.2.2 POST Topic Service)
- createDocument - The ability to create a new document (see 4.8.2 POST Document Service)
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)
- updateBimSnippet - The ability to update the BIM snippet for topics (see 4.2.7 PUT Topic BIM Snippet Service)
- updateRelatedTopics - The ability to update the collection of related topics (see 4.6.2 PUT Related Topics Service)
- updateDocumentReferences - The ability to update the collection of document references (see 4.7.3 PUT Document Reference Service)
- updateFiles - The ability to update the file header (see 4.3.2 PUT Files (Header) Service)
- createComment - The ability to create a comment (see 4.4.2 POST Comment Service)
- createViewpoint - The ability to create a new viewpoint (see 4.5.2 POST Viewpoint Service)
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)
Resource URL
GET /bcf/{version}/projects/{project_id}/topics
Retrieve a collection of topics related to a project (default sort order is creation_date
).
Odata filter parameters
parameter | type | description |
---|---|---|
creation_author | string | userId of the creation author (value from extensions) |
modified_author | string | userId of the modified author (value from extensions) |
assigned_to | string | userId of the assigned person (value from extensions) |
stage | string | stage this topic is part of (value from extensions) |
topic_status | string | status of a topic (value from extensions) |
topic_type | string | type of a topic (value from extensions) |
creation_date | datetime | creation date of a topic |
modified_date | datetime | modification date of a topic |
labels | array (string) | labels of a topic (value from extensions) |
Odata sort parameters
parameter | description |
---|---|
creation_date | creation date of a topic |
modified_date | modification date of a topic |
index | index of a topic |
Example Request with odata
Get topics that are open, assigned to Architect@example.com and created after December 5th 2015. Sort the result on last modified
GET /bcf/2.1/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics?$filter=assigned_to eq 'Architect@example.com' and topic_status eq 'Open' and creation_date gt 2015-12-05T00:00:00+01:00&$orderby=modified_date desc
Odata does not support list operators. To achieve list query, use the 'or' operator. Get topics that have at least one of the labels 'Architecture', 'Structural' or 'Heating'
GET /bcf/1.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics?$filter=contains(labels, 'Architecture') or contains(labels, 'Structural') or contains(labels, 'Heating')
Example Request
GET /bcf/2.1/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics
Example Response
Response Code: 200 - OK
Body:
[{
"guid": "A245F4F2-2C01-B43B-B612-5E456BEF8116",
"creation_author": "Architect@example.com",
"title": "Example topic 1",
"labels": [
"Architecture",
"Structural"
],
"creation_date": "2013-10-21T17:34:22.409Z"
}, {
"guid": "A211FCC2-3A3B-EAA4-C321-DE22ABC8414",
"creation_author": "Architect@example.com",
"title": "Example topic 2",
"labels": [
"Architecture",
"Heating",
"Electrical"
],
"creation_date": "2014-11-19T14:24:11.316Z"
}]
Resource URL
POST /bcf/{version}/projects/{project_id}/topics
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
Parameters
JSON encoded body using the "application/json" content type.
Parameter | Type | Description | Required |
---|---|---|---|
topic_type | string | The type of a topic (value from extension.xsd) | false |
topic_status | string | The status of a topic (value from extension.xsd) | false |
reference_links | array (string) | Reference links, i.e. links to referenced resources | false |
title | string | The title of a topic | true |
priority | string | The priority of a topic (value from extension.xsd) | false |
index | integer | The index of a topic | false |
labels | array (string) | The collection of labels of a topic (values from extension.xsd) | false |
assigned_to | string | UserID assigned to a topic (value from extension.xsd). UserIDs are recommended to be in email format as to uniquely identify users throughout multiple systems | false |
stage | string | Stage this topic is part of (value from extension.xsd) | false |
description | string | Description of a topic | false |
bim_snippet.snippet_type | string | Type of a BIM-Snippet of a topic (value from extension.xsd) | false |
bim_snippet.is_external | boolean | Is the BIM-Snippet external (default = false) | false |
bim_snippet.reference | string | Reference of a BIM-Snippet of a topic | false |
bim_snippet.reference_schema | string | Schema of a BIM-Snippet of a topic | false |
due_date | string | Until when the topics issue needs to be resolved | false |
Note: If "bim_snippet" is present, then all four properties (snippet_type
, is_external
, reference
and reference_schema
) are mandatory.
Example Request
POST /bcf/2.1/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics
Body:
{
"topic_type": "Clash",
"topic_status": "open",
"title": "Example topic 3",
"priority": "high",
"labels": [
"Architecture",
"Heating"
],
"assigned_to": "harry.muster@example.com",
"bim_snippet": {
"snippet_type": "clash",
"is_external": true,
"reference": "https://example.com/bcf/1.0/ADFE23AA11BCFF444122BB",
"reference_schema": "https://example.com/bcf/1.0/clash.xsd"
}
}
Example Response
Response Code: 201 - Created
Body:
{
"guid": "A245F4F2-2C01-B43B-B612-5E456BEF8116",
"creation_author": "Architect@example.com",
"creation_date": "2016-08-01T17:34:22.409Z",
"topic_type": "Clash",
"topic_status": "open",
"title": "Example topic 3",
"priority": "high",
"labels": [
"Architecture",
"Heating"
],
"assigned_to": "harry.muster@example.com",
"bim_snippet": {
"snippet_type": "clash",
"is_external": true,
"reference": "https://example.com/bcf/1.0/ADFE23AA11BCFF444122BB",
"reference_schema": "https://example.com/bcf/1.0/clash.xsd"
}
}
Resource URL
GET /bcf/{version}/projects/{guid}/topics/{guid}
Retrieve a specific topic.
Example Request
GET /bcf/2.1/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228
Example Response
Response Code: 200 - OK
Body:
{
"guid": "B345F4F2-3A04-B43B-A713-5E456BEF8228",
"creation_author": "Architect@example.com",
"creation_date": "2016-08-01T17:34:22.409Z",
"topic_type": "Clash",
"topic_status": "open",
"title": "Example topic 3",
"priority": "high",
"labels": [
"Architecture",
"Heating"
],
"assigned_to": "harry.muster@example.com",
"bim_snippet": {
"snippet_type": "clash",
"is_external": true,
"reference": "https://example.com/bcf/1.0/ADFE23AA11BCFF444122BB",
"reference_schema": "https://example.com/bcf/1.0/clash.xsd"
},
"authorization": {
"topic_actions": [
"createComment",
"createViewpoint"
]
}
}
Resource URL
PUT /bcf/{version}/projects/{project_id}/topics/{guid}
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
Example Request
PUT /bcf/2.1/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228
Body:
{
"topic_type": "Clash",
"topic_status": "open",
"title": "Example topic 3 - Changed Title",
"priority": "high",
"labels": [
"Architecture",
"Heating"
],
"assigned_to": "harry.muster@example.com",
"bim_snippet": {
"snippet_type": "clash",
"is_external": true,
"reference": "https://example.com/bcf/1.0/ADFE23AA11BCFF444122BB",
"reference_schema": "https://example.com/bcf/1.0/clash.xsd"
}
}
Example Response
Response Code: 200 - OK
Body:
{
"guid": "B345F4F2-3A04-B43B-A713-5E456BEF8228",
"creation_author": "Architect@example.com",
"creation_date": "2016-08-01T17:34:22.409Z",
"modified_author": "Architect@example.com",
"modified_date": "2016-08-02T13:22:22.409Z",
"topic_type": "Clash",
"topic_status": "open",
"title": "Example topic 3 - Changed Title",
"priority": "high",
"labels": [
"Architecture",
"Heating"
],
"assigned_to": "harry.muster@example.com",
"bim_snippet": {
"snippet_type": "clash",
"is_external": true,
"reference": "https://example.com/bcf/1.0/ADFE23AA11BCFF444122BB",
"reference_schema": "https://example.com/bcf/1.0/clash.xsd"
}
}
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
Example Request
DELETE /bcf/2.1/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228
Example Response
Response Code: 200 - OK
Resource URL
GET /bcf/{version}/projects/{project_id}/topics/{guid}/snippet
Retrieves a topics BIM-Snippet as binary file.
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
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.
Resource URL
GET /bcf/{version}/projects/{project_id}/topics/{guid}/files
Retrieve a collection of file references as topic header.
Implementer Note: The reference
property can either be an Uri or a server specific id. Uris are given as absolute paths to the model files while ids reference a custom id of the model file and require custom logic per server to retrieve it. This allows referencing of files on the server but requires clients to know how to retrieve files in a specific implementation.
Example Request
GET /bcf/2.1/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/files
Example Response
Response Code: 200 - OK
Body:
[{
"ifc_project": "0J$yPqHBD12v72y4qF6XcD",
"file_name": "OfficeBuilding_Architecture_0001.ifc",
"reference": "https://example.com/files/0J$yPqHBD12v72y4qF6XcD_0001.ifc"
}, {
"ifc_project": "3hwBHP91jBRwPsmyf$3Hea",
"file_name": "OfficeBuilding_Heating_0003.ifc",
"reference": "cf37bae6-0900-46be-b37f-b34754fe0b4a"
}]
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.
Resource URL
PUT /bcf/{version}/projects/{project_id}/topics/{guid}/files
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
Example Request
PUT /bcf/1.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/files
Body:
[{
"ifc_project": "0J$yPqHBD12v72y4qF6XcD",
"file_name": "OfficeBuilding_Architecture_0001.ifc",
"reference": "https://example.com/files/0J$yPqHBD12v72y4qF6XcD_0001.ifc"
}, {
"ifc_project": "3hwBHP91jBRwPsmyf$3Hea",
"file_name": "OfficeBuilding_Heating_0003.ifc",
"reference": "https://example.com/files/3hwBHP91jBRwPsmyf$3Hea_0003.ifc"
}]
Example Response
Response Code: 200 - OK
Body:
[{
"ifc_project": "0J$yPqHBD12v72y4qF6XcD",
"file_name": "OfficeBuilding_Architecture_0001.ifc",
"reference": "https://example.com/files/0J$yPqHBD12v72y4qF6XcD_0001.ifc"
}, {
"ifc_project": "3hwBHP91jBRwPsmyf$3Hea",
"file_name": "OfficeBuilding_Heating_0003.ifc",
"reference": "https://example.com/files/3hwBHP91jBRwPsmyf$3Hea_0003.ifc"
}]
Resource URL
GET /bcf/{version}/projects/{project_id}/topics/{guid}/comments
Retrieve a collection of all comments related to a topic (default ordering is date).
Odata filter parameters
parameter | type | description |
---|---|---|
author | string | userId of the author (value from extensions) |
date | datetime | creation date of a comment |
Odata sort parameters
parameter | description |
---|---|
date | creation date of a comment |
Example Request with odata
Get comments that are created after December 5 2015. Sort the result on first created
GET /bcf/1.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/comments?$filter=date gt 2015-12-05T00:00:00+01:00&$orderby=date asc
Example Request
GET /bcf/1.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/comments
Example Response
Response Code: 200 - OK
Body:
[{
"guid": "C4215F4D-AC45-A43A-D615-AA456BEF832B",
"date": "2016-08-01T12:34:22.409Z",
"author": "max.muster@example.com",
"comment": "Clash found",
"topic_guid": "B345F4F2-3A04-B43B-A713-5E456BEF8228",
"authorization": {
"comment_actions": [
"update"
]
}
}, {
"guid": "A333FCA8-1A31-CAAC-A321-BB33ABC8414",
"date": "2016-08-01T14:24:11.316Z",
"author": "bob.heater@example.com",
"comment": "will rework the heating model",
"topic_guid": "B345F4F2-3A04-B43B-A713-5E456BEF8228"
}]
Resource URL
POST /bcf/{version}/projects/{project_id}/topics/{guid}/comments
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
Parameters
JSON encoded body using the "application/json" content type.
Parameter | Type | Description | Required |
---|---|---|---|
comment | string | The comment text | true |
viewpoint_guid | string | The GUID of the related viewpoint | false |
reply_to_comment_guid | string | GUID of the comment to which this comment replies to | false |
Example Request
POST /bcf/2.1/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/comments
Body:
{
"comment": "will rework the heating model"
}
Example Response
Response Code: 201 - Created
Body:
{
"guid": "A333FCA8-1A31-CAAC-A321-BB33ABC8414",
"date": "2016-08-01T14:24:11.316Z",
"author": "bob.heater@example.com",
"comment": "will rework the heating model",
"topic_guid": "B345F4F2-3A04-B43B-A713-5E456BEF8228"
}
Resource URL
GET /bcf/{version}/projects/{project_id}/topics/{guid}/comments/{guid}
Get a single comment.
Example Request
GET /bcf/2.1/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/comments/A333FCA8-1A31-CAAC-A321-BB33ABC8414
Example Response
Response Code: 200 - OK
Body:
{
"guid": "A333FCA8-1A31-CAAC-A321-BB33ABC8414",
"date": "2016-08-01T14:24:11.316Z",
"author": "bob.heater@example.com",
"comment": "will rework the heating model",
"topic_guid": "B345F4F2-3A04-B43B-A713-5E456BEF8228"
}
Resource URL
PUT /bcf/{version}/projects/{project_id}/topics/{guid}/comments/{guid}
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
Example Request
PUT /bcf/2.1/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/comments/A333FCA8-1A31-CAAC-A321-BB33ABC8414
Body:
{
"comment": "will rework the heating model and fix the ventilation"
}
Example Response
Response Code: 200 - OK
Body:
{
"guid": "A333FCA8-1A31-CAAC-A321-BB33ABC8414",
"date": "2016-08-01T14:24:11.316Z",
"author": "bob.heater@example.com",
"modified_date": "2016-08-01T19:24:11.316Z",
"modified_author": "bob.heater@example.com",
"comment": "will rework the heating model and fix the ventilation",
"topic_guid": "B345F4F2-3A04-B43B-A713-5E456BEF8228"
}
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
Example Request
DELETE /bcf/2.1/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/comments/A333FCA8-1A31-CAAC-A321-BB33ABC8414
Example Response
Response Code: 200 - OK
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.
Resource URL
GET /bcf/{version}/projects/{project_id}/topics/{guid}/viewpoints
Retrieve a collection of all viewpoints related to a topic.
Example Request
GET /bcf/2.1/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/viewpoints
Example Response
Response Code: 200 - OK
Body:
[{
"guid": "b24a82e9-f67b-43b8-bda0-4946abf39624",
"perspective_camera": {
"camera_view_point": {
"x": 0.0,
"y": 0.0,
"z": 0.0
},
"camera_direction": {
"x": 1.0,
"y": 1.0,
"z": 2.0
},
"camera_up_vector": {
"x": 0.0,
"y": 0.0,
"z": 1.0
},
"field_of_view": 90.0
},
"lines": [{
"start_point": {
"x": 2.0,
"y": 1.0,
"z": 1.0
},
"end_point": {
"x": 0.0,
"y": 1.0,
"z": 0.7
}
}],
"clipping_planes": [{
"location": {
"x": 0.7,
"y": 0.3,
"z": -0.2
},
"direction": {
"x": 1.0,
"y": 0.4,
"z": 0.1
}
}]
}, {
"guid": "a11a82e7-e66c-34b4-ada1-5846abf39133",
"perspective_camera": {
"camera_view_point": {
"x": 0.0,
"y": 0.0,
"z": 0.0
},
"camera_direction": {
"x": 1.0,
"y": 1.0,
"z": 2.0
},
"camera_up_vector": {
"x": 0.0,
"y": 0.0,
"z": 1.0
},
"field_of_view": 90.0
},
"lines": [{
"start_point": {
"x": 1.0,
"y": 1.0,
"z": 1.0
},
"end_point": {
"x": 0.0,
"y": 0.0,
"z": 0.0
}
}],
"clipping_planes": [{
"location": {
"x": 0.5,
"y": 0.5,
"z": 0.5
},
"direction": {
"x": 1.0,
"y": 0.0,
"z": 0.0
}
}]
}]
Resource URL
POST /bcf/{version}/projects/{project_id}/topics/{guid}/viewpoints
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
Parameters
JSON encoded body using the "application/json" content type.
parameter | type | description | required |
---|---|---|---|
index | integer | parameter for sorting | optional |
orthogonal camera | Orthogonal camera | orthogonal camera view | optional |
perspective camera | Perspective camera | perspective view of the camera | optional |
lines | array of Line | graphical line | optional |
clipping_planes | array of Clipping Plane | clipping planes for the model view | optional |
bitmaps | array of Bitmap | embedded pictures in the viewpoint | optional |
snapshot | Snapshot | snapshot image of the viewpoint | optional |
components | Components | Components in the viewpoint | optional |
parameter | type | description | required |
---|---|---|---|
x | number | x point | mandatory |
y | number | y point | mandatory |
z | number | z point | mandatory |
parameter | type | description | required |
---|---|---|---|
x | number | x direction | mandatory |
y | number | y direction | mandatory |
z | number | z direction | mandatory |
parameter | type | description | required |
---|---|---|---|
camera_view_point | Direction | viewpoint of the camera | mandatory |
camera_direction | Direction | direction of the camera | mandatory |
camera_up_vector | Direction | direction of camera up | mandatory |
view_to_world_scale | number | proportion of camera view to model | mandatory |
parameter | type | description | required |
---|---|---|---|
camera_view_point | Point | viewpoint of the camera | mandatory |
camera_direction | Direction | direction of the camera | mandatory |
camera_up_vector | Direction | direction of camera up | mandatory |
field_of_view | number | field of view | mandatory |
parameter | type | description | required |
---|---|---|---|
start_point | Point | start point of the line | mandatory |
end_point | Point | end point of the line (Treated as point if start_point and end_point is the same | mandatory |
parameter | type | description | required |
---|---|---|---|
location | Point | origin of the clipping plane | mandatory |
direction | Direction | direction of the clipping plane | mandatory |
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 | location of the center of the bitmap in world coordinates (point) | mandatory |
normal | Direction | normal vector of the bitmap (vector) | mandatory |
up | Direction | up vector of the bitmap (vector) | mandatory |
height | number | height of bitmap in the scene | mandatory |
parameter | type | description | required |
---|---|---|---|
snapshot_type | enum (string) | format of the snapshot. Predefined values png or jpg |
mandatory |
snapshot_data | base64 encoded string | The snapshot image data | mandatory |
parameter | type | description | required |
---|---|---|---|
selection | array of Component | Selected components | optional |
coloring | array of Coloring | Colored components | optional |
visibility | Visibility | Visibility of components | mandatory |
BCF is suitable for selecting a few components. A huge list of selected components causes poor performance. All clients should follow this rule:
- If the size of the selected components is huge (approximately 1000 components), alert the user and give him the opportunity to modify the visibility.
parameter | type | description | required |
---|---|---|---|
ifc_guid | string | IFC guid of the component | optional |
originating_system | string | originating system of the component | optional |
authoring_tool_id | string | internal id for the authoring tool of the component | optional |
BCF is suitable for coloring a few components. A huge list of components causes poor performance. All clients should follow this rule:
- If the size of colored components is huge (approximately 1000 components), alert the user and give him the opportunity to modify the coloring.
The color is given in ARGB format. Colors are represented as 6 or 8 hexadecimal digits. If 8 digits are present, the first two represent the alpha (transparency) channel. For example, 40E0D0
would be the color <span style="color:#40E0D0;";>Turquoise. More information about the color format can be found on Wikipedia.
parameter | type | description | required |
---|---|---|---|
color | string | Color of the components | mandatory |
components | array of Component | Colored components | mandatory |
BCF is suitable for hiding/showing a few components. A huge list of hidden/shown components causes poor performance. All clients should follow these rules:
- If the list of hidden components is smaller than the list of visible components: set default_visibility to true and put the hidden components in exceptions.
- If the list of visible components is smaller or equals the list of hidden components: set default_visibility to false and put the visible components in exceptions.
- If the size of exceptions is huge (approximately 1000 components), alert the user and give him the opportunity to modify the visibility.
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 | Components to hide/show determined by default_visibility | optional |
view_setup_hints | View setup hints | Hints about the setup of the viewer | optional |
parameter | type | description | required |
---|---|---|---|
spaces_visible | boolean | Visibility of spaces | optional, default false |
space_boundaries_visible | Visibility of space_boundaries | optional, default false | |
openings_visible | boolean | Visibility of openings | optional, default false |
Example Request
POST /bcf/2.1/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/viewpoints
Body:
{
"index": 10,
"perspective_camera": {
"camera_view_point": {
"x": 0.0,
"y": 0.0,
"z": 0.0
},
"camera_direction": {
"x": 1.0,
"y": 1.0,
"z": 2.0
},
"camera_up_vector": {
"x": 0.0,
"y": 0.0,
"z": 1.0
},
"field_of_view": 90.0
},
"lines": [{
"start_point": {
"x": 1.0,
"y": 1.0,
"z": 1.0
},
"end_point": {
"x": 0.0,
"y": 0.0,
"z": 0.0
}
}],
"clipping_planes": [{
"location": {
"x": 0.5,
"y": 0.5,
"z": 0.5
},
"direction": {
"x": 1.0,
"y": 0.0,
"z": 0.0
}
}],
"bitmaps": [{
"bitmap_type": "jpg",
"bitmap_data": "SGVsbG8gV29ybGQh",
"location": {
"x": 10.0,
"y": -10.0,
"z": 7.0
},
"normal": {
"x": -1.0,
"y": 1.25,
"z": 0.0
},
"up": {
"x": -5.4,
"y": -4.3,
"z": 1.0
},
"height": 1666
}],
"snapshot": {
"snapshot_type": "png",
"snapshot_data": "SGVsbG8gV29ybGQh"
},
"components": {
"selection": [{
"ifc_guid": "2MF28NhmDBiRVyFakgdbCT",
"originating_system": "Example CAD Application",
"authoring_tool_id": "EXCAD/v1.0"
}],
"coloring": [{
"color": "#ff0000",
"components": [{
"ifc_guid": "3$cshxZO9AJBebsni$z9Yk"
}]
}],
"visibility": {
"default_visbility": false,
"exceptions": [{
"ifc_guid": "4$cshxZO9AJBebsni$z9Yk"
}],
"view_setup_hints": {
"spaces_visible": true,
"space_boundaries_visible": false,
"openings_visible": true
}
}
}
}
Example Response
Response Code: 201 - Created
Body:
{
"guid": "a11a82e7-e66c-34b4-ada1-5846abf39133",
"index": 10,
"perspective_camera": {
"camera_view_point": {
"x": 0.0,
"y": 0.0,
"z": 0.0
},
"camera_direction": {
"x": 1.0,
"y": 1.0,
"z": 2.0
},
"camera_up_vector": {
"x": 0.0,
"y": 0.0,
"z": 1.0
},
"field_of_view": 90.0
},
"lines": [{
"start_point": {
"x": 1.0,
"y": 1.0,
"z": 1.0
},
"end_point": {
"x": 0.0,
"y": 0.0,
"z": 0.0
}
}],
"clipping_planes": [{
"location": {
"x": 0.5,
"y": 0.5,
"z": 0.5
},
"direction": {
"x": 1.0,
"y": 0.0,
"z": 0.0
}
}],
"bitmaps": [{
"guid": "20c1cb56-315f-4a0a-922d-ed7a4a8edf55",
"bitmap_type": "jpg",
"location": {
"x": 10.0,
"y": -10.0,
"z": 7.0
},
"normal": {
"x": -1.0,
"y": 1.25,
"z": 0.0
},
"up": {
"x": -5.4,
"y": -4.3,
"z": 1.0
},
"height": 1666
}],
"snapshot": {
"snapshot_type": "png"
}
}
Resource URL
GET /bcf/{version}/projects/{guid}/topics/{guid}/viewpoints/{guid}
Retrieve a specific viewpoint.
Example Request
GET /bcf/2.1/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/viewpoints/a11a82e7-e66c-34b4-ada1-5846abf39133
Example Response
Response Code: 200 - OK
Body:
{
"guid": "a11a82e7-e66c-34b4-ada1-5846abf39133",
"index": 10,
"perspective_camera": {
"camera_view_point": {
"x": 0.0,
"y": 0.0,
"z": 0.0
},
"camera_direction": {
"x": 1.0,
"y": 1.0,
"z": 2.0
},
"camera_up_vector": {
"x": 0.0,
"y": 0.0,
"z": 1.0
},
"field_of_view": 90.0
},
"lines": [{
"start_point": {
"x": 1.0,
"y": 1.0,
"z": 1.0
},
"end_point": {
"x": 0.0,
"y": 0.0,
"z": 0.0
}
}],
"clipping_planes": [{
"location": {
"x": 0.5,
"y": 0.5,
"z": 0.5
},
"direction": {
"x": 1.0,
"y": 0.0,
"z": 0.0
}
}],
"bitmaps": [{
"guid": "20c1cb56-315f-4a0a-922d-ed7a4a8edf55"
"bitmap_type": "jpg",
"location": {
"x": 10.0,
"y": -10.0,
"z": 7.0
},
"normal": {
"x": -1.0,
"y": 1.25,
"z": 0.0
},
"up": {
"x": -5.4,
"y": -4.3,
"z": 1.0
},
"height": 1666
}],
"snapshot": {
"snapshot_type": "png"
}
}
Resource URL
GET /bcf/{version}/projects/{guid}/topics/{guid}/viewpoints/{guid}/snapshot
Retrieve a viewpoints snapshot (png or jpg) as image file. A viewpoint contains a snapshot if viewpoint.snapshot != null.
Example Request
GET /bcf/2.1/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/viewpoints/a11a82e7-e66c-34b4-ada1-5846abf39133/snapshot
Resource URL
GET /bcf/{version}/projects/{guid}/topics/{guid}/viewpoints/{guid}/bitmaps/{guid}
Retrieve a specific viewpoints bitmap image file (png or jpg).
Example Request 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
Resource URL
GET /bcf/{version}/projects/{project_id}/topics/{guid}/viewpoints/{guid}/selection
Retrieve a collection of all selected components in a viewpoint.
Example Request
GET /bcf/2.1/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/viewpoints/a11a82e7-e66c-34b4-ada1-5846abf39133/selection
Example Response
Response Code: 200 - OK
Body:
{
"selection": [
{
"ifc_guid": "2MF28NhmDBiRVyFakgdbCT",
"originating_system": "Example CAD Application",
"authoring_tool_id": "EXCAD/v1.0"
}, {
"ifc_guid": "3$cshxZO9AJBebsni$z9Yk"
}
]
}
Resource URL
GET /bcf/{version}/projects/{project_id}/topics/{guid}/viewpoints/{guid}/coloring
Retrieve a collection of all colored components in a viewpoint.
Example Request
GET /bcf/2.1/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/viewpoints/a11a82e7-e66c-34b4-ada1-5846abf39133/selection
Example Response
Response Code: 200 - OK
Body:
{
"coloring": [
{
"color": "#ff0000",
"components": [
{
"ifc_guid": "2MF28NhmDBiRVyFakgdbCT",
"originating_system": "Example CAD Application",
"authoring_tool_id": "EXCAD/v1.0"
}, {
"ifc_guid": "3$cshxZO9AJBebsni$z9Yk"
}
]
}
]
}
Resource URL
GET /bcf/{version}/projects/{project_id}/topics/{guid}/viewpoints/{guid}/visibility
Retrieve visibility of components in a viewpoint.
Example Request
GET /bcf/2.1/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/viewpoints/a11a82e7-e66c-34b4-ada1-5846abf39133/visibility
Example Response
Response Code: 200 - OK
Body:
{
"visibility": {
"default_visibility": true,
"exceptions": [
{
"ifc_guid": "2MF28NhmDBiRVyFakgdbCT",
"originating_system": "Example CAD Application",
"authoring_tool_id": "EXCAD/v1.0"
}, {
"ifc_guid": "3$cshxZO9AJBebsni$z9Yk",
}
],
"view_setup_hints": {
"spaces_visible": true,
"space_boundaries_visible": false,
"openings_visible": true
}
}
}
Resource URL
GET /bcf/{version}/projects/{project_id}/topics/{guid}/related_topics
Retrieve a collection of all related topics to a topic.
Example Request
GET /bcf/2.1/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/related_topics
Example Response
Response Code: 200 - OK
Body:
[{
"related_topic_guid": "db49df2b-0e42-473b-a3ee-f7b785d783c4"
}, {
"related_topic_guid": "6963a846-54d1-4050-954d-607cd5e48aa3"
}]
Resource URL
PUT /bcf/{version}/projects/{project_id}/topics/{guid}/related_topics
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
Example Request
PUT /bcf/2.1/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/related_topics
Body:
[{
"related_topic_guid": "db49df2b-0e42-473b-a3ee-f7b785d783c4"
}, {
"related_topic_guid": "6963a846-54d1-4050-954d-607cd5e48aa3"
}, {
"related_topic_guid": "bac66ab4-331e-4f21-a28e-083d2cf2e796"
}]
Example Response
Response Code: 200 - OK
Body:
[{
"related_topic_guid": "db49df2b-0e42-473b-a3ee-f7b785d783c4"
}, {
"related_topic_guid": "6963a846-54d1-4050-954d-607cd5e48aa3"
}, {
"related_topic_guid": "bac66ab4-331e-4f21-a28e-083d2cf2e796"
}]
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.
Resource URL
GET /bcf/{version}/projects/{project_id}/topics/{guid}/document_references
Retrieve a collection of all document references to a topic.
Example Request
GET /bcf/2.1/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/document_references
Example Response
Response Code: 200 - OK
Body:
[{
"guid": "212ab37a-6122-448e-86fc-86503183b520",
"url": "http://example.com/files/LegalRequirements.pdf",
"description": "The legal requirements for buildings."
}, {
"guid": "6cbfe31d-95c3-4f4d-92a6-420c23698721",
"document_guid": "472ab37a-6122-448e-86fc-86503183b520",
"description": "The building owners global design parameters for buildings."
}]
Resource URL
POST /bcf/{version}/projects/{project_id}/topics/{guid}/document_references
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
Should either reference an internal or an external document.
- Internal
- document_guid must match an existing document in the project
- url must be null
- External
- document_guid must be null
- url must be the url to the external resource
Example Request
POST /bcf/2.1/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/document_references
Body:
{
"url": "http://example.com/files/LegalRequirements.pdf",
"description": "The legal requirements for buildings."
}
Example Response
Response Code: 201 - Created
Body:
{
"guid": "275ab37a-6122-448e-86fc-86503183b520",
"url": "http://example.com/files/LegalRequirements.pdf",
"description": "The legal requirements for buildings."
}
Example Request
POST /bcf/2.1/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/document_references
Body:
{
"document_guid": "472ab37a-6122-448e-86fc-86503183b520",
"description": "The building owners global design parameters for buildings."
}
Example Response
Response Code: 201 - Created
Body:
{
"guid": "135ab37a-6122-448e-86fc-86503183b520",
"document_guid": "472ab37a-6122-448e-86fc-86503183b520",
"description": "The building owners global design parameters for buildings."
}
Resource URL
PUT /bcf/{version}/projects/{project_id}/topics/{guid}/document_references/{guid}
Update an existing document reference identified by guid.
Uses the same rules as 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
Example Request
PUT /bcf/2.1/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/document_references/472ab37a-6122-448e-86fc-86503183b520
Body:
{
"guid": "135ab37a-6122-448e-86fc-86503183b520",
"url": "http://example.com/files/LegalRequirements_Update.pdf",
"description": "The legal requirements for buildings."
}
Example Response
Response Code: 200 - OK
Body:
{
"guid": "135ab37a-6122-448e-86fc-86503183b520",
"url": "http://example.com/files/LegalRequirements_Update.pdf",
"description": "The legal requirements for buildings."
}
Resource URL
GET /bcf/{version}/projects/{project_id}/documents
Retrieve a collection of all documents uploaded to a project.
Example Request
GET /bcf/2.1/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/documents
Example Response
Response Code: 200 - OK
Body:
[{
"guid": "472ab37a-6122-448e-86fc-86503183b520",
"filename": "LegalRequirements.pdf"
}, {
"guid": "6cbfe31d-95c3-4f4d-92a6-420c23698721",
"filename": "DesignParameters.pdf"
}]
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
Example Request
POST /bcf/2.1/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/documents
Example Response
Response Code: 201 - Created
Body:
{
"guid": "472ab37a-6122-448e-86fc-86503183b520",
"filename": "Official_Building_Permission.pdf"
}
Resource URL
GET /bcf/{version}/projects/{project_id}/documents/{guid}
Retrieves a document as binary file.
Example Request
GET /bcf/2.1/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/documents/472ab37a-6122-448e-86fc-86503183b520
Example Response
Retrieves a document as binary file.
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.
Resource URL
GET /bcf/{version}/projects/{project_id}/topics/events
Retrieve a collection of topic events related to a project (default sort order is date
).
Topic event types
type | value |
---|---|
topic_created | null |
title_updated | The title (limit: 128 characters) |
description_updated | The description (limit: 1024 characters) |
description_removed | null |
status_updated | The status (value from extensions) |
type_updated | The type (value from extensions) |
priority_updated | The priority (value from extensions) |
priority_removed | null |
due_date_updated | The due date |
due_date_removed | null |
assigned_to_updated | The assigned user (value from extensions) |
assigned_to_removed | null |
label_added | The label added (value from extensions) |
label_removed | The label removed (value from extensions) |
Odata filter parameters
parameter | type | description |
---|---|---|
topic_guid | string | guid of the topic |
author | string | userId of the author (value from extensions) |
type | string | type of the event (value from Topic event types, table above) |
date | datetime | date of the event |
Odata sort parameters
parameter | description |
---|---|
date | date of the event |
Example Request with odata
Get events of type 'status_updated' made by Architect@example.com and created after December 5th 2015. Sort the result on least recent
GET /bcf/2.1/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/events?$filter=author eq 'Architect@example.com' and type eq 'status_updated' and date gt 2015-12-05T00:00:00+01:00&$orderby=date asc
Get latest events of given topic. Skip the 10 first, and get the 5 next
GET /bcf/2.1/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/events?$filter=topic_guid eq 'A245F4F2-2C01-B43B-B612-5E456BEF8116'&$top=5&$skip=10
Get events that are of type 'status_updated', 'type_updated' or 'title_updated' or 'label_added'
/bcf/1.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/events?$filter=type eq 'status_updated' or type eq 'type_updated' or type eq 'title_updated' or type eq 'label_added'
Example Request
GET /bcf/2.1/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/events
Example Response
Response Code: 200 - OK
Body:
[{
"topic_guid": "A211FCC2-3A3B-EAA4-C321-DE22ABC8414",
"date": "2014-11-19T14:24:11.316Z",
"author": "Architect@example.com",
"events": [
{
"type": "status_updated",
"value": "Closed"
}
]
}, {
"topic_guid": "A245F4F2-2C01-B43B-B612-5E456BEF8116",
"date": "2013-10-21T17:34:22.409Z",
"author": "Architect@example.com",
"events": [
{
"type": "type_updated",
"value": "Warning"
}
]
}]
Resource URL
GET /bcf/{version}/projects/{project_id}/topics/{topic_guid}/events
Retrieve a collection of topic events related to a project (default sort order is date
).
Topic event types
type | value |
---|---|
topic_created | null |
title_updated | The title (limit: 128 characters) |
description_updated | The description (limit: 1024 characters) |
description_removed | null |
status_updated | The status (value from extensions) |
type_updated | The type (value from extensions) |
priority_updated | The priority (value from extensions) |
priority_removed | null |
due_date_updated | The due date |
due_date_removed | null |
assigned_to_updated | The assigned user (value from extensions) |
assigned_to_removed | null |
label_added | The label added (value from extensions) |
label_removed | The label removed (value from extensions) |
Odata filter parameters
parameter | type | description |
---|---|---|
author | string | userId of the author (value from extensions) |
type | string | type of the event (value from Topic event types, table above) |
date | datetime | date of the event |
Odata sort parameters
parameter | description |
---|---|
date | date of the event |
Example Request with odata
Get events of type 'status_updated' made by Architect@example.com and created after December 5th 2015. Sort the result on least recent
GET /bcf/2.1/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/A245F4F2-2C01-B43B-B612-5E456BEF8116/events?$filter=author eq 'Architect@example.com' and type eq 'status_updated' and date gt 2015-12-05T00:00:00+01:00&$orderby=date asc
Get latest events. Skip the 10 first, and get the 5 next
GET /bcf/2.1/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/A245F4F2-2C01-B43B-B612-5E456BEF8116/events?$top=5&$skip=10
Odata does not support list operators. To achieve list query, use the 'or' operator. Get events that is of type 'status_updated', 'type_updated' or 'title_updated' or 'label_added'
/bcf/1.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/A245F4F2-2C01-B43B-B612-5E456BEF8116/events?$filter=type eq 'status_updated' or type eq 'type_updated' or type eq 'title_updated' or type eq 'label_updated'
Example Request
GET /bcf/2.1/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/A245F4F2-2C01-B43B-B612-5E456BEF8116/events
Example Response
Response Code: 200 - OK
Body:
[{
"topic_guid": "A245F4F2-2C01-B43B-B612-5E456BEF8116",
"date": "2014-11-19T14:24:11.316Z",
"author": "Architect@example.com",
"events": [
{
"type": "type_updated",
"value": "Error"
}
]
}, {
"topic_guid": "A245F4F2-2C01-B43B-B612-5E456BEF8116",
"date": "2013-10-21T17:34:22.409Z",
"author": "Architect@example.com",
"events": [
{
"type": "status_updated",
"value": "Open"
}
]
}]
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.
Resource URL
GET /bcf/{version}/projects/{project_id}/topics/comments/events
Retrieve a collection of comment events related to a project (default sort order is date
).
Comment event types
type | value |
---|---|
comment_created | null |
comment_text_updated | The comment text(limit: 1024 characters) |
viewpoint_updated | The viewpoint guid |
viewpoint_removed | null |
reply_to_comment_updated | The reply to comment guid |
reply_to_comment_removed | null |
Odata filter parameters
parameter | type | description |
---|---|---|
comment_guid | string | guid of the comment |
topic_guid | string | guid of the topic |
author | string | userId of the author (value from extensions) |
date | datetime | date of the event |
type | string | type of the event (value from Comment event types, table above) |
Odata sort parameters
parameter | description |
---|---|
date | date of the event |
Example Request with odata
Get events of type 'comment_created' made by Architect@example.com and created after December 5th 2015. Sort the result on least recent
GET /bcf/2.1/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/comments/events?$filter=author eq 'Architect@example.com' and date gt 2015-12-05T00:00:00+01:00 and type eq 'comment_created'&$orderby=date asc
Get latest events of given comment. Skip the 10 first, and get the 5 next
GET /bcf/2.1/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/comments/events?$filter=comment_guid eq 'C4215F4D-AC45-A43A-D615-AA456BEF832B'&$top=5&$skip=10
Get events that are of type 'comment_created', or 'viewpoint_updated'
/bcf/1.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/events?$filter=type eq 'comment_created' or type eq 'viewpoint_updated'
Example Request
GET /bcf/2.1/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/comments/events
Example Response
Response Code: 200 - OK
Body:
[{
"comment_guid": "C4215F4D-AC45-A43A-D615-AA456BEF832B",
"topic_guid": "A211FCC2-3A3B-EAA4-C321-DE22ABC8414",
"date": "2014-11-19T14:24:11.316Z",
"author": "Architect@example.com",
"events": [
{
"type": "comment_created",
"value": null
}
]
}, {
"comment_guid": "C4215F4D-AC45-A43A-D615-AA456BEF832B",
"topic_guid": "A245F4F2-2C01-B43B-B612-5E456BEF8116",
"date": "2013-10-21T17:34:22.409Z",
"author": "Architect@example.com",
"events": [
{
"type": "viewpoint_updated",
"value": "b24a82e9-f67b-43b8-bda0-4946abf39624"
}
]
}]
Resource URL
GET /bcf/{version}/projects/{project_id}/topics/{topic_guid}/comments/{comment_guid}/events
Retrieve a collection of comment events related to a comment (default sort order is date
).
Comment event types
type | value |
---|---|
comment_created | null |
comment_text_updated | The comment text(limit: 1024 characters) |
viewpoint_updated | The viewpoint guid |
viewpoint_removed | null |
reply_to_comment_updated | The reply to comment guid |
reply_to_comment_removed | null |
Odata filter parameters
parameter | type | description |
---|---|---|
author | string | userId of the author (value from extensions) |
date | datetime | date of the event |
type | string | type of the event (value from Comment event types, table above) |
Odata sort parameters
parameter | description |
---|---|
date | date of the event |
Example Request with odata
Get events of type 'comment_created' made by Architect@example.com and created after December 5th 2015. Sort the result on least recent
GET /bcf/2.1/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/A211FCC2-3A3B-EAA4-C321-DE22ABC8414/comments/C4215F4D-AC45-A43A-D615-AA456BEF832B/events?$filter=author eq 'Architect@example.com' and date gt 2015-12-05T00:00:00+01:00 and type eq 'comment_created'&$orderby=date asc
Get latest events of given comment. Skip the 10 first, and get the 5 next
GET /bcf/2.1/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/A211FCC2-3A3B-EAA4-C321-DE22ABC8414/comments/C4215F4D-AC45-A43A-D615-AA456BEF832B/events?$top=5&$skip=10
Get events that are of type 'comment_created', or 'comment_text_updated'
GET /bcf/2.1/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/A211FCC2-3A3B-EAA4-C321-DE22ABC8414/comments/C4215F4D-AC45-A43A-D615-AA456BEF832B/events?$filter=type eq 'comment_created' or type eq 'viewpoint_updated'
Example Request
GET /bcf/2.1/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/A211FCC2-3A3B-EAA4-C321-DE22ABC8414/comments/C4215F4D-AC45-A43A-D615-AA456BEF832B/events
Example Response
Response Code: 200 - OK
Body:
[{
"comment_guid": "C4215F4D-AC45-A43A-D615-AA456BEF832B",
"topic_guid": "A211FCC2-3A3B-EAA4-C321-DE22ABC8414",
"date": "2014-11-19T14:24:11.316Z",
"author": "Architect@example.com",
"events": [
{
"type": "comment_created",
"value": null
}
]
}, {
"comment_guid": "C4215F4D-AC45-A43A-D615-AA456BEF832B",
"topic_guid": "A245F4F2-2C01-B43B-B612-5E456BEF8116",
"date": "2013-10-21T17:34:22.409Z",
"author": "Architect@example.com",
"events": [
{
"type": "comment_text_updated",
"value": "This is the updated comment"
}
]
}]