Relationships API is a shared service used in BIM 360 and Autodesk Construction Cloud (ACC). A relationship defines a link between items (Entity) that reside in different modules (Domain). In BIM 360 and ACC UI, you can typically see them as a reference: for example, an asset may have links to checklists, issues and document attachments, where an asset resides in Asset Management, while a checklist and an issue reside in Field Management, and an attachment in Document Management.
Relationship web service keeps track of the instance of relationships created among different domains. In Relationship Service, an item to link, such as a checklist and an asset, is called Entity. Entity is composed of three properties: domain, type and id. In case of checklist, domain is autodesk-bim360-checklist, and type is checklist. It could be checklist template. id is an id of checklist. An entity for an Asset is defined in similar manner. It's a simple and clean data structure.
Relationship web service exposes a set of endpoints to Read. What’s powerful about this API is that this simple structure provides a way to save and search those relationships independent from the implementation detail of each component.
Using this API, you can:
- Read, search, create and delete relationships or references.
- Synchronize relationships using optional synchronization token.
Additional information about this that Relationships API are:
- The API is compatible with BIM 360 and ACC
- It supports 3-legged token only
- Important: not all modules make use of relationships API at this point. Older modules that existed before relationships API was introduced do not use this API. Assets makes use of this API extensively. You can use relationships:writable utility to check if you can use it to identify writable relationships.
- Currently it is not possible to define custom relationships.
You can find more information from the AU presentations which talk about this API:
- SD468487 “BIM 360 API Update and Beyond” (AU 2020)
This includes Assets and Relationships API for read and search. In the recording, relationships starts at 26:59. The page 31 of presentation slides. The page 13 of handouts.
- CS500022 "Construction Cloud API Update and Beyond" (AU 2021)
This includes updates about Relationships API for write access. In the recording, relationships starts at 25:12. The page 41 of presentation slides. Page 17th of handouts.