Version 1.0 based on BCFv2. GitHub repository
Table of Contents
- 1. Introduction
- 2. Topologies
- 3. Public Services
- 4. BCF Services
BCF is a format for managing issues on a BIM project. RESTful BCF-API supports the exchange of BCFv2 issues between software applications.
All API access is transmitted over HTTPS. Data is sent as URL encoded query parameters and JSON POST bodies and received as JSON. Every resource has a corresponding JSON Schema (Draft 03). JSON Hyper Schema is used for link definition. The authentication method is OAuth2. URL schemas in this readme are relational to the base server URL.
An example of a client implementation in C# can be found here: https://github.com/rvestvik/BcfApiExampleClient
When requesting collections of items, BCF-API offers the possibility of paging via URL parameters.
| page | The current page in the paginated collection. |
| page_size | The number of items per page. Defaults to 100 if not given, maximum is 1000 items per page. |
Example:
GET /bcf/{version}/projects/{guid}/topics?page=11&page_size=20
Returns topics #201 to #220.
GET requests for collections offer sorting of results via the "sort" URL parameter. Every JSON element can be used as a sorting parameter. Default sort order is ascending. Descending order is indicated with an unary minus sign "-" in front of an element.
Multiple sort parameters are possible and separated with commas.
Example:
/bcf/{version}/projects/{guid}/topics?sort=-priority,label
Would return a collection of topics sorted by priority (descending) then by label (ascending).
GET requests returning a collection can be filtered with the "filter" URL parameter. The syntax is based on the ODATA protocol. Wildcard operator is allowed as the star sign (*). Doubel quotes (") in string literals are escaped by a backslash () character, for example: "Hotel "Mountain Inn" Reconstruction".
Filter operators:
| eq | equals | /topics?filter=label eq Architecture |
| ne | not equals | /topics?filter=topic_status ne closed |
| gt | greater than | /topics?filter=creation_date gt 2013* |
| ge | greater than or equal | /topics?filter=creation_date ge 2013* |
| lt | less than | /topics?filter=creation_date lt 2013* |
| le | less than or equal | /topics?filter=creation_date le 2013* |
| and | logical and | /topics?filter=label eq Architecture and priority eq high |
| or | logical or | /topics?filter=label eq Architecture or label eq Structural |
| ( ) | grouping parentheses | /topics?filter=(label eq Architecture or label eq Structural) and priority eq high |
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 https://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, the resource may also partially updated with a HTTP PATCH query that only transports the changed properties of the entity.
The server will put the "Access-Control-Allow-Headers" in the response header and specify who can access the servers (JSON) resources. The client can look for this value and proceed with accessing the resources.
The server has a web config file .. "*" means the server allow the resources for all domains.
<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>
- 200 OK (Data is returned)
- 201 No content (Data has been deleted)
- 302 Redirect (Returning a redirect to the GET-resource for the data that has been created/updated)
- 400 BadRequest (Input data is invalid)
- 401 Unauthorized (User don’t have access to the requested resource)
- 403 Forbidden
- 404 Not found (It must be discussed if the user should get “unauthorized” to resources he don’t have access to, or “not found")
- 422 Unprocessable entity (Input data is well formed, but the semantic is wrong; Example: Resource define that a value cannot be “null”, but the value is “null”)
BCF-API has a specified error response body format error.json.
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.
Recource URL (public resource)
GET /bcf/version
Parameters
| version_id | string | ID of the version | mandatory |
| detailed_version | string | URL to version on Github | optional |
Example Request
https://example.com/bcf/version
Example Response
{
"version_id": "1.0",
"detailed_version": "https://github.com/BuildingSMART/BCF-API",
}
Authentication is based on the OAuth 2.0 Protocol.
Recource URL (public resource)
GET /bcf/auth
Parameters
| oauth2_auth_url | string | URL to authorisation page | mandatory |
| oauth2_token_url | string | URL for token requests | mandatory |
| oauth2_dynamic_client_reg_url | string | URL for automated client registration | optional |
Example Request
https://example.com/bcf/auth
Example Response
{
"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"
}
The Client uses the "oauth2_auth_url" and adds the following parameters to it.
| response_type | "code" |
| client_id | your client_id |
| state | unique user defined value |
Example URL:
https://example.com/bcf/oauth2/auth?response_type=code&client_id=<YourClientID>&state=D98F9B4F-5B0E-4948-B8B5-59F4FE23B8E0
Example redirected URL:
https://YourWebsite.com/retrieveCode?code=ABC1234567890XYZ&state=D98F9B4F-5B0E-4948-B8B5-59F4FE23B8E0
Tip: You can use the state parameter to transport custom information.
Open a browser window or redirect the user to this resource. This redirects back to the specified redirect URI with the provided state and the authorization code as a query parameter if the user allows your app to access the account, the value "access_denied" in the error query parameter if the user denies access.
The Client uses the "oauth2_token_url" to request a token. Example:
POST https://example.com/bcf/oauth2/token
Content type: application/x-www-form-urlencoded.
Parameters
| access_token | string | The issued OAuth2 token | mandatory |
| token_type | string | Always "bearer" | mandatory |
| expires_in | integer | The lifetime of the access token in seconds | mandatory |
| refresh_token | string | The issued OAuth2 refresh token, one-time-usable only | mandatory |
The POST request has to be done via HTTP Basic Authorization. Your applications "ClientID" is the username, your "ClientSecret" is the password.
Post Request Body:
grant_type=authorization_code&code=<YourAccessCode>
The access token will be returned as JSON in the response body and is an arbitrary string, guaranteed to fit in a varchar(255) field.
Example Response
{
"access_token":"Zjk1YjYyNDQtOTgwMy0xMWU0LWIxMDAtMTIzYjkzZjc1Y2Jh",
"token_type":"bearer",
"expires_in":"3600",
"refresh_token":"MTRiMjkzZTYtOTgwNC0xMWU0LWIxMDAtMTIzYjkzZjc1Y2Jh"
}
The process to retrieve a refresh token is exactly the same as retrieving a token except the POST Request Body.
POST Request Body:
grant_type=refresh_token&refresh_token=<YourRefreshToken>
The refresh token can only be used once to retrieve a token and a new refresh token.
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.
Recource URL
POST <oauth2_dynamic_client_reg_url> (obtained from auth_GET)
Register a new client :
Parameters
JSON encoded body using the "application/json" content type.
| client_name | string (max. 60) | The client name |
| client_description | string (max. 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
https://example.com/bcf/oauth2/reg
{
"client_name": "Example Application",
"client_description": "Example CAD desktop application",
"client_url": "https://example.com",
"redirect_url": "https://localhost:8080"
}
Example Response
{
"client_id": "cGxlYXN1cmUu"
"client_secret": "ZWFzdXJlLg==",
}
When requesting other resources the access token must be passed via the Authorization header using the Bearer scheme (e.g. Authorization: Bearer T9UNRV4sC9vr7ga).
Recource URL
GET /bcf/{version}/projects
Retrieve a collection of projects where the currently logged on user has access to.
Example Request
https://example.com/bcf/1.0/projects
Example Response
[{
"project_id": "F445F4F2-4D02-4B2A-B612-5E456BEF9137",
"name": "Example project 1"
},
{
"project_id": "A233FBB2-3A3B-EFF4-C123-DE22ABC8414",
"name": "Example project 2"
}]
Recource URL
POST /bcf/{version}/projects
Add a new project.
Parameters
JSON encoded body using the "application/json" content type.
| name | string | The project name |
Example Request
https://example.com/bcf/1.0/projects
{
"name": "Example project 3"
}
Example Response
{
"project_id": "B724AAC3-5B2A-234A-D143-AE33CC18414"
"name": "Example project 3",
}
Recource URL
GET /bcf/{version}/projects/{project_id}
Retrieve a specific project.
Example Request
https://example.com/bcf/1.0/projects/B724AAC3-5B2A-234A-D143-AE33CC18414
Example Response
{
"project_id": "B724AAC3-5B2A-234A-D143-AE33CC18414",
"name": "Example project 3"
}
Recource URL
PUT /bcf/{version}/projects/{project_id}
Modify a specific project, description similar to POST.
Recource URL
GET /bcf/{version}/projects/{project_id}/extensions
Retrieve a specific projects extensions.
Example Request
https://example.com/bcf/1.0/projects/B724AAC3-5B2A-234A-D143-AE33CC18414/extensions
Example Response
{
"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":
[
"[email protected]",
"[email protected]",
"[email protected]"
]
}
Recource URL
POST /bcf/{version}/projects/{project_id}/extensions
Create 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.
Parameters
JSON encoded body using the "application/json" content type.
| topic_type | string array | Enumeration of allowed values |
| topic_status | string array | Enumeration of allowed values |
| topic_label | string array | Enumeration of allowed values |
| snippet_type | string array | Enumeration of allowed values |
| priority | string array | Enumeration of allowed values |
| user_id_type | string array | Enumeration of allowed values |
Example Request
https://example.com/bcf/1.0/projects/B724AAC3-5B2A-234A-D143-AE33CC18414/extensions
{
"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":
[
"[email protected]",
"[email protected]",
"[email protected]"
]
}
Example Response
{
"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":
[
"[email protected]",
"[email protected]",
"[email protected]"
]
}
Recource URL
PUT /bcf/{version}/projects/{project_id}/extensions
Modify a specific projects extensions, description similar to POST.
Recource URL
GET /bcf/{version}/projects/{project_id}/topics
Retrieve a collection of topics related to a project (default sort order is creation_date).
Example Request
https://example.com/bcf/1.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics
Example Response
[
{
"guid": "A245F4F2-2C01-B43B-B612-5E456BEF8116",
"title": "Example topic 1",
"labels": [
"Architecture",
"Structural"
],
"creation_date": "2013-10-21T17:34:22.409Z"
},
{
"guid": "A211FCC2-3A3B-EAA4-C321-DE22ABC8414",
"title": "Example topic 2",
"labels": [
"Architecture",
"Heating",
"Electrical"
],
"creation_date": "2014-11-19T14:24:11.316Z"
}
]
Recource URL
POST /bcf/{version}/projects/{project_id}/topics
Add a new topic.
Parameters
JSON encoded body using the "application/json" content type.
| topic_type | string | The type of a topic (value from extension.xsd) | optional |
| topic_status | string | The status of a topic (value from extension.xsd) | optional |
| reference_link | string | Reference link | optional |
| title | string | The title of a topic | mandatory |
| priority | string | The priority of a topic (value from extension.xsd) | optional |
| index | integer | The index of a topic | optional |
| labels | string | The collection of labels of a topic (values from extension.xsd) | optional |
| assigned_to | string | UserID assigned to a topic (value from extension.xsd) | optional |
| description | string | Description of a topic | optional |
| snippet_type | string | Type of a BIM-Snippet of a topic (value from extension.xsd) | mandatory if BIM-Snippet exists |
| is_external | boolean | Is the BIM-Snippet external (default = false) | optional |
| reference | string | Reference of a BIM-Snippet of a topic | mandatory if BIM-Snippet exists |
| reference_schema | string | Schema of a BIM-Snippet of a topic | mandatory if BIM-Snippet exists |
Example Request
https://example.com/bcf/1.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics
{
"topic_type": "Clash",
"topic_status": "open",
"title": "Example topic 3",
"priority": "high",
"labels": [
"Architecture",
"Heating"],
"assigned_to": "[email protected]",
"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"
}
}
Recource URL
GET /bcf/{version}/topics/{guid}
GET /bcf/{version}/projects/{guid}/topics/{guid}
Retrieve a specific topic.
Example Request
https://example.com/bcf/1.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228
Example Response
{
"guid": "B345F4F2-3A04-B43B-A713-5E456BEF8228",
"topic_type": "Clash",
"topic_status": "open",
"title": "Example topic 3",
"priority": "high",
"labels": [
"Architecture",
"Heating"],
"assigned_to": "[email protected]",
"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"
}
}
Recource URL
PUT /bcf/{version}/topics/{guid}
PUT /bcf/{version}/projects/{project_id}/topics/{guid}
Modify a specific topic, description similar to POST.
Resource URL
GET /bcf/{version}/topics/{guid}/snippet
GET /bcf/{version}/projects/{project_id}/topics/{guid}/snippet
Retrieves a topics BIM-Snippet as binary file. Will use the following HTTP headers to deliver additional information:
Content-Type: application/octet-stream;
Content-Length: {Size of file in bytes};
Content-Disposition: attachment; filename="{Filename.extension}";
Resource URL
PUT /bcf/{version}/topics/{guid}/snippet
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 must be set to "is_external"=false and the "reference" must be the file name with extension. The following HTTP headers are used for the upload:
Content-Type: application/octet-stream;
Content-Length: {Size of file in bytes};
Recource URL
GET /bcf/{version}/topics/{guid}/files
GET /bcf/{version}/projects/{project_id}/topics/{guid}/files
Retrieve a collection of file references as topic header.
Example Request
https://example.com/bcf/1.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/files
Example Response
[
{
"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"
}
]
Recource URL
PUT /bcf/{version}/topics/{guid}/files
PUT /bcf/{version}/projects/{project_id}/topics/{guid}/files
Update a collection of file references on the topic header.
Example Request
https://example.com/bcf/1.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/files
[
{
"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
[
{
"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"
}
]
Recource URL
GET /bcf/{version}/topics/{guid}/comments
GET /bcf/{version}/projects/{project_id}/topics/{guid}/comments
Retrieve a collection of all comments related to a topic.
Example Request
https://example.com/bcf/1.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/comments
Example Response
[
{
"guid": "C4215F4D-AC45-A43A-D615-AA456BEF832B",
"status": "open",
"date": "2013-10-21T17:34:22.409Z",
"author": "[email protected]",
"comment": "Clash found",
"topic_guid": "B345F4F2-3A04-B43B-A713-5E456BEF8228"
},
{
"guid": "A333FCA8-1A31-CAAC-A321-BB33ABC8414",
"status": "closed",
"date": "2013-11-19T14:24:11.316Z",
"author": "[email protected]",
"comment": "will rework the heating model",
"topic_guid": "B345F4F2-3A04-B43B-A713-5E456BEF8228"
}
]
Recource URL
POST /bcf/{version}/topics/{guid}/comments
POST /bcf/{version}/projects/{project_id}/topics/{guid}/comments
Add a new comment to a topic.
Parameters
JSON encoded body using the "application/json" content type.
| verbal_status | string | The verbal status of a comment (possible values from extension.xsd) | optional |
| status | string | The status of a comment (default unknown) | mandatory |
| comment | string | The comment | mandatory |
| viewpoint_guid | string | The GUID of the related viewpoint | optional |
| reply_to_comment_guid | string | GUID of the comment to which this comment replies to | optional |
Example Request
https://example.com/bcf/1.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/comments
{
"verbal_status": "closed",
"status": "closed",
"comment": "will rework the heating model",
}
Example Response
{
"guid": "A333FCA8-1A31-CAAC-A321-BB33ABC8414",
"verbal_status": "closed",
"status": "closed",
"date": "2013-11-19T14:24:11.316Z",
"author": "[email protected]",
"comment": "will rework the heating model",
"topic_guid": "B345F4F2-3A04-B43B-A713-5E456BEF8228"
}
Recource URL
GET /bcf/{version}/comments/{guid}
GET /bcf/{version}/projects/{project_id}/topics/{guid}/comments/{guid}
Get a single comment.
Example Request
https://example.com/bcf/1.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/comments/A333FCA8-1A31-CAAC-A321-BB33ABC8414
Example Response
{
"guid": "A333FCA8-1A31-CAAC-A321-BB33ABC8414",
"verbal_status": "closed",
"status": "closed",
"date": "2013-11-19T14:24:11.316Z",
"author": "[email protected]",
"comment": "will rework the heating model",
"topic_guid": "B345F4F2-3A04-B43B-A713-5E456BEF8228"
}
Recource URL
PUT /bcf/{version}/comments/{guid}
PUT /bcf/{version}/projects/{project_id}/topics/{guid}/comments/{guid}
Update a single comment, description similar to POST.
Recource URL
GET /bcf/{version}/topics/{guid}/viewpoints
GET /bcf/{version}/projects/{project_id}/topics/{guid}/viewpoints
Retrieve a collection of all viewpoints related to a topic.
Example Request
https://example.com/bcf/1.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/viewpoints
Example Response
[
{
"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":{
"line":[
{
"start_point":{
"x":2.0,
"y":1.0,
"z":1.0},
"end_point":{
"x":0.0,
"y":1.0,
"z":0.7}
}
]},
"clipping_planes":{
"clipping_plane":[
{
"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":{
"line":[
{
"start_point":{
"x":1.0,
"y":1.0,
"z":1.0},
"end_point":{
"x":0.0,
"y":0.0,
"z":0.0}
}
]},
"clipping_planes":{
"clipping_plane":[
{
"location":{
"x":0.5,
"y":0.5,
"z":0.5},
"direction":{
"x":1.0,
"y":0.0,
"z":0.0}
}
]
}
}
]
Recource URL
POST /bcf/{version}/topics/{guid}/viewpoints
POST /bcf/{version}/projects/{project_id}/topics/{guid}/viewpoints
Add a new viewpoint.
Parameters
JSON encoded body using the "application/json" content type.
| x, y, z | number | Numbers defining ether a point or a vector | optional |
| orthogonal camera | element | Orthogonal camera view | optional |
| camera_view_point | element | Viewpoint of the camera | optional |
| camera_directiont | element | Direction of the camera | optional |
| camera_up_vector | element | Direction of camera up | optional |
| view_to_world_scale | element | Proportion of camera view to model | optional |
| perspective camera | element | Perspective view of the camera | optional |
| camera_view_point | element | Viewpoint of the camera | optional |
| camera_directiont | element | Direction of the camera | optional |
| camera_up_vector | element | Direction of camera up | optional |
| field_of_view | element | Field of view | optional |
| line | element | A graphical line | optional |
| start_point | element | Start point of the line | optional |
| end_point | element | end point of the line | optional |
| clipping_plane | element | Clipping plane for the model view | optional |
| location | element | Origin of the clipping plane | optional |
| direction | element | direction of the clipping plane | optional |
| snapshot | element | Picture of the viewpoint | optional |
| enum | string | Format of the bitmap. Predefined values "png", "jpg", "bmp" | optional |
| reference | string | Url to image | optional |
| location | element | Location of the center of the bitmap in world coordinates (point) | optional |
| normal | element | Normal vector of the bitmap (vector) | optional |
| up | element | Up vector of the bitmap (vector) | optional |
Example Request
https://example.com/bcf/1.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/viewpoints
{
"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":{
"line":[
{
"start_point":{
"x":1.0,
"y":1.0,
"z":1.0},
"end_point":{
"x":0.0,
"y":0.0,
"z":0.0}
}
]},
"clipping_planes":{
"clipping_plane":[
{
"location":{
"x":0.5,
"y":0.5,
"z":0.5},
"direction":{
"x":1.0,
"y":0.0,
"z":0.0}
}
]
}
}
Example Response
{
"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":{
"line":[
{
"start_point":{
"x":1.0,
"y":1.0,
"z":1.0},
"end_point":{
"x":0.0,
"y":0.0,
"z":0.0}
}
]},
"clipping_planes":{
"clipping_plane":[
{
"location":{
"x":0.5,
"y":0.5,
"z":0.5},
"direction":{
"x":1.0,
"y":0.0,
"z":0.0}
}
]
}
}
Recource URL
GET /bcf/{version}/viewpoints/{guid}
GET /bcf/{version}/projects/{guid}/topics/{guid}/viewpoints/{guid}
Retrieve a specific viewpoint.
Example Request
https://example.com/bcf/1.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/viewpoints/a11a82e7-e66c-34b4-ada1-5846abf39133
Example Response
{
"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":{
"line":[
{
"start_point":{
"x":1.0,
"y":1.0,
"z":1.0},
"end_point":{
"x":0.0,
"y":0.0,
"z":0.0}
}
]},
"clipping_planes":{
"clipping_plane":[
{
"location":{
"x":0.5,
"y":0.5,
"z":0.5},
"direction":{
"x":1.0,
"y":0.0,
"z":0.0}
}
]
}
}
Recource URL
PUT /bcf/{version}/viewpoints/{guid}
PUT /bcf/{version}/projects/{guid}/topics/{guid}/viewpoints/{guid}
Update a single viewpoint, description similar to POST.
Recource URL
GET /bcf/{version}/viewpoints/{guid}/snapshot
GET /bcf/{version}/projects/{guid}/topics/{guid}/viewpoints/{guid}/snapshot
Retrieve a viewpoints image (png, jpg or bmp).
Example Request
https://example.com/bcf/1.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/viewpoints/a11a82e7-e66c-34b4-ada1-5846abf39133/snapshot
Example Response
HTTP-response header:
Content-Type: image/png
Recource URL
PUT /bcf/{version}/viewpoints/{guid}/snapshot
PUT /bcf/{version}/projects/{guid}/topics/{guid}/viewpoints/{guid}/snapshot
Add or update a viewpoints image (png, jpg or bmp).
Example Request
https://example.com/bcf/1.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/viewpoints/a11a82e7-e66c-34b4-ada1-5846abf39133/snapshot
HTTP PUT request header:
Content-Type: image/png
PUT Body contains binary image data
Example Response
HTTP-response status code:
201 created (empty response body)
Recource URL
GET /bcf/{version}/viewpoints/{guid}/components
GET /bcf/{version}/projects/{project_id}/topics/{guid}/viewpoints/{guid}/components
Retrieve a collection of all components related to a viewpoint.
Example Request
https://example.com/bcf/1.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/viewpoints/a11a82e7-e66c-34b4-ada1-5846abf39133/components
Example Response
[
{
"ifc_guid":"2MF28NhmDBiRVyFakgdbCT",
"selected": true,
"visible": true,
"color":"0A00FF",
"originating_system":"Example CAD Application",
"authoring_tool_id":"EXCAD/v1.0"
},
{
"ifc_guid":"3$cshxZO9AJBebsni$z9Yk",
"selected": true,
"visible": true,
"color":"0A00FF",
"originating_system":"Example CAD Application",
"authoring_tool_id":"EXCAD/v1.0"
}
]
Recource URL
POST /bcf/{version}/viewpoints/{guid}/components
POST /bcf/{version}/projects/{project_id}/topics/{guid}/viewpoints/{guid}/components
Add or update a collection of all components related to a viewpoint.
Example Request
https://example.com/bcf/1.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/viewpoints/a11a82e7-e66c-34b4-ada1-5846abf39133/components
[
{
"ifc_guid":"2MF28NhmDBiRVyFakgdbCT",
"selected": true,
"visible": true,
"color":"0A00FF",
"originating_system":"Example CAD Application",
"authoring_tool_id":"EXCAD/v1.0"
},
{
"ifc_guid":"3$cshxZO9AJBebsni$z9Yk",
"selected": true,
"visible": true,
"color":"0A00FF",
"originating_system":"Example CAD Application",
"authoring_tool_id":"EXCAD/v1.0"
}
]
Example Response
[
{
"ifc_guid":"2MF28NhmDBiRVyFakgdbCT",
"selected": true,
"visible": true,
"color":"0A00FF",
"originating_system":"Example CAD Application",
"authoring_tool_id":"EXCAD/v1.0"
},
{
"ifc_guid":"3$cshxZO9AJBebsni$z9Yk",
"selected": true,
"visible": true,
"color":"0A00FF",
"originating_system":"Example CAD Application",
"authoring_tool_id":"EXCAD/v1.0"
}
]
Recource URL
GET /bcf/{version}/topics/{guid}/related_topics
GET /bcf/{version}/projects/{project_id}/topics/{guid}/related_topics
Retrieve a collection of all related topics to a topic.
Example Request
https://example.com/bcf/1.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/related_topics
Example Response
[
{
"related_topic_guid":"db49df2b-0e42-473b-a3ee-f7b785d783c4",
},
{
"related_topic_guid":"6963a846-54d1-4050-954d-607cd5e48aa3",
}
]
Recource URL
POST /bcf/{version}/topics/{guid}/related_topics
POST /bcf/{version}/projects/{project_id}/topics/{guid}/related_topics
Add or update a collection of all related topics to a topic.
Example Request
https://example.com/bcf/1.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/related_topics
[
{
"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
[
{
"related_topic_guid":"db49df2b-0e42-473b-a3ee-f7b785d783c4"
},
{
"related_topic_guid":"6963a846-54d1-4050-954d-607cd5e48aa3"
},
{
"related_topic_guid":"bac66ab4-331e-4f21-a28e-083d2cf2e796"
}
]
Recource URL
GET /bcf/{version}/topics/{guid}/document_references
GET /bcf/{version}/projects/{project_id}/topics/{guid}/document_references
Retrieve a collection of all document references to a topic.
Example Request
https://example.com/bcf/1.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/document_references
Example Response
[
{
"guid":"472ab37a-6122-448e-86fc-86503183b520",
"referenced_document":"https://example.com/files/LegalRequirements.pdf",
"description":"The legal requirements for buildings."
},
{
"guid":"6cbfe31d-95c3-4f4d-92a6-420c23698721",
"referenced_document":"https://example.com/files/DesignParameters.pdf",
"description":"The building owners global design parameters for buildings."
}
]
Recource URL
POST /bcf/{version}/topics/{guid}/document_references
POST /bcf/{version}/projects/{project_id}/topics/{guid}/document_references
Add or update document references to a topic. The PUT object may either contain the property "guid" to reference a document stored on the BCF server (see section 4.9) OR the property "referenced_document" to point to an external resource.
Example Request
https://example.com/bcf/1.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/document_references
[
{
"referenced_document":"https://example.com/files/LegalRequirements.pdf",
"description":"The legal requirements for buildings."
}
]
Example Response
[
{
"guid":"472ab37a-6122-448e-86fc-86503183b520",
"referenced_document":"https://example.com/files/LegalRequirements.pdf",
"description":"The legal requirements for buildings."
}
]
Recource URL
GET /bcf/{version}/projects/{project_id}/documents
Retrieve a collection of all documents uploaded to a project.
Example Request
https://example.com/bcf/1.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/documents
Example Response
[
{
"guid":"472ab37a-6122-448e-86fc-86503183b520",
"filename":"LegalRequirements.pdf"
},
{
"guid":"6cbfe31d-95c3-4f4d-92a6-420c23698721",
"filename":"DesignParameters.pdf"
}
]
Recource URL
POST /bcf/{version}/projects/{project_id}/documents
Upload a document (binary file) to a project. The following HTTP headers are used for the upload:
Content-Type: application/octet-stream;
Content-Length: {Size of file in bytes};
Content-Disposition: attachment; filename="{Filename.extension}";
Example Response
{
"guid":"472ab37a-6122-448e-86fc-86503183b520",
"filename":"Official_Building_Permission.pdf"
}
Recource URL
GET /bcf/{version}/projects/{project_id}/documents/{guid}
Retrieves a document as binary file. Will use the following HTTP headers to deliver additional information:
Content-Type: application/octet-stream;
Content-Length: {Size of file in bytes};
Content-Disposition: attachment; filename="{Filename.extension}";