DOCSEARCHbyAlgolia
Submit Docs

BIM Collaboration Format (BCF) REST API

repository·release_3_0·Indexed 42 days ago

https://github.com/buildingsmart/bcf-api

An open standard RESTful interface for managing and exchanging BIM (Building Information Modeling) issues, viewpoints, and comments between software applications. Part of the OpenCDE API family, it provides endpoints for project management, topic coordination, BIM snippet handling, and per-entity authorization using JSON schema (draft-03) and OData filtering.

Tokens
10.4K
Snippets
31
Records
42
Agent score
4%

What's inside BCF API

  1. Overview of the BCF REST API

    release_3_0

    The BuildingSMART BCF (BIM Collaboration Format) REST API is an open standard for managing issues within a BIM project. It enables the exchange of BCF issues between different software applications using a RESTful web interface. Data exchange is performed via HTTP query parameters and JSON bodies, following JSON schema (draft-03).

    Key implementation requirements:

    • Security: All API HTTP traffic must be sent via TLS/SSL over HTTPS. Both clients and servers should enforce secure connections and disallow unsafe connections.
    • Foundation: The BCF API is a member of the OpenCDE API family. All implementations must implement the OpenCDE Foundation API and follow its conventions before implementing BCF-specific services.

  2. How comment authorization works

    release_3_0

    Comment permissions (like update, createComment, or delete) are determined by the server.

    Global default authorizations are defined in the project schema. To see specific local overrides for individual comments, request them using the query parameter includeAuthorization=true. When this is used, each comment object in the response will include an authorization field containing the applicable permissions.

  3. Understand Topic Identifiers: GUID vs server_assigned_id

    release_3_0

    Every topic in the BCF API is identified by two distinct types of IDs:

    1. guid: A machine-friendly, randomly generated, and universally unique identifier (UUID) following RFC 4122. Clients must generate a guid when creating a topic. This guid should be used for all client-server interactions to identify topics.

      • Example: 420b24db-921c-46d6-9629-d529d130307f

    2. server_assigned_id: A human-friendly identifier generated and controlled by the server. It is unique within a specific project on a specific server, but may be duplicated across different projects on the same server. These IDs cannot be changed via the API and should be used for display to users to facilitate discussion.

      • Example: ISSUE-01 or 003490

  4. How Topic Authorization works

    release_3_0

    Authorization for topic modifications is handled via flags returned by the server:

    • Global Defaults: Default authorizations are expressed in the project schema.
    • Local Overrides: When requesting topics with the query parameter includeAuthorization=true, the response includes an authorization field for each topic. This field contains local overrides for that specific topic.
    • Required Flags: To perform specific actions, the server must return the corresponding flag in the authorization object:
      • createTopic (at Project level) to allow creating new topics.
      • update (at Topic level) to allow modifying a topic.
      • delete (at Topic level) to allow deleting a topic.
      • updateBimSnippet (at Topic level) to allow uploading binary BIM snippets.

  5. Understand the structure of a Comment Event response

    release_3_0

    A successful request to the comment events service returns a JSON array of objects. Each object represents a comment and its associated events.

    Response Object Schema:

    • comment_guid: The unique identifier for the comment.
    • topic_guid: The unique identifier for the topic.
    • date: The timestamp of the event.
    • author: The identifier of the user who performed the action.
    • events: An array of event objects, each containing:
      • type: The specific event type (e.g., comment_created).
      • value: The data associated with the event (e.g., the viewpoint GUID or comment text).
    [
    {
        "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
            }
        ]
    }
]

  6. Optimize component selection, coloring, and visibility

    release_3_0

    When working with components in viewpoints, follow these optimization rules to prevent performance degradation in clients:

    Selection and Coloring

    • If the number of selected or colored components is large (approximately 1000), alert the user and provide an option to modify the selection/coloring.

    Visibility

    To minimize the size of the exceptions array, use the default_visibility flag strategically:

    • 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 than or equal to the list of hidden components: Set default_visibility to false and put the visible components in exceptions.
    • Threshold: If the exceptions list reaches approximately 1000 components, alert the user and allow them to modify visibility.

  7. Filter and sort topic events using OData

    release_3_0

    Both the project-level and topic-level event services support OData query parameters for filtering and sorting.

    Filter Parameters

    • topic_guid (string): GUID of the topic (Project-level service only).
    • author (string): userId of the author.
    • type (string): The type of the event (e.g., status_updated).
    • date (datetime): The date of the event.

    Sort Parameters

    • date: Sort by the date of the event.

    Querying Multiple Types

    OData does not support list operators. To query multiple event types, use the or operator (e.g., type eq 'status_updated' or type eq 'type_updated').

    GET /bcf/3.0/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

  8. Configure Viewpoint authorization

    release_3_0
    Viewpoint authorizations (like createViewpoint or delete) are defined by the project schema. To see local overrides for specific viewpoints, include the includeAuthorization=true query parameter when requesting Viewpoints. This will add an authorization field to the returned Viewpoint objects.

  9. How Per-Entity Authorization works in BCF

    release_3_0

    BCF API implementers can restrict user actions on entities (like Topics, Comments, or Viewpoints) using an authorization model.

    Mechanism:

    1. Global Defaults: Project-wide authorization defaults are defined in the Project Extensions schema.
    2. Local Overrides: When a client requests an updateable entity with the query parameter includeAuthorization=true, the server returns an authorization field within that entity. This field contains local variations that override the global defaults.
    3. Client Logic: Clients should calculate available actions by taking the project-wide defaults from the project extensions and replacing any keys found in the entity's local authorization map.

    Example (Topic Authorization): If the Project Extension defines that no topic modifications are allowed by default, but a specific Topic entity returns:

    "authorization": {
    "topic_actions": ["update", "createComment", "createViewpoint"],
    "topic_status": ["open", "closed"]
}

    Then the client knows the user can specifically update this topic, add comments/viewpoints to it, and transition its status between open and closed.

    // Example of local authorization override in a Topic entity
{
    "authorization": {
        "topic_actions": [
            "update",
            "createComment",
            "createViewpoint"
        ],
        "topic_status": [
            "open",
            "closed"
        ]
    }
}

  10. Understand project extension authorization

    release_3_0

    Project extensions allow the server to express global default authorizations for a user. These actions apply to all entities unless they are overridden locally (e.g., at the specific topic or comment level).

    Project Actions

    Found in project_actions. Defines what can be done at the project level:

    • update: Modify project details.
    • createTopic: Create a new topic.
    • createDocument: Create a new document.

    Topic Actions

    Found in topic_actions. Defines default permissions for topics:

    • update: Update the topic.
    • updateBimSnippet: Update the BIM snippet.
    • updateRelatedTopics: Update related topics.
    • updateDocumentReferences: Update document references.
    • updateFiles: Update the file header.
    • createComment: Create a comment.
    • createViewpoint: Create a new viewpoint.

    Comment Actions

    Found in comment_actions. Defines default permissions for comments:

    • update: Update the comment.

  12. Add a new comment to a topic

    release_3_0

    Use POST /bcf/{version}/projects/{project_id}/topics/{guid}/comments to add a comment. This requires the createComment flag in the Topic authorization.

    Request Body (JSON):

    • comment (string, required unless viewpoint_guid is provided): The comment text.
    • viewpoint_guid (string, required unless comment is provided): The GUID of the related viewpoint.
    • guid (string, optional): The desired GUID for the comment.
    POST /bcf/3.0/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics/B345F4F2-3A04-B43B-A713-5E456BEF8228/comments
{
    "comment": "will rework the heating model"
}