Skip to content

Commit cf84c1a

Browse files
GeorgDanglGeorgDangl
committed
Merge branch 'feature/mergePr29'
2 parents e2d9d9d + c71a76c commit cf84c1a

File tree

6 files changed

+331
-46
lines changed

6 files changed

+331
-46
lines changed

‎README.md‎

Lines changed: 218 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -12,11 +12,14 @@
1212
* [1.1 Paging, Sorting and Filtering](#11-paging-sorting-and-filtering)
1313
* [1.2 Caching](#12-caching)
1414
* [1.3 Updating Resources via HTTP PUT](#13-updating-resources-via-http-put)
15-
* [1.4 Cross Origin Resource Sharing (Cors)](#14-cross-origin-resource-sharing-cors)
15+
* [1.4 Cross Origin Resource Sharing (CORS)](#14-cross-origin-resource-sharing-cors)
1616
* [1.5 Http Status Codes](#15-http-status-codes)
1717
* [1.6 Error Response Body Format](#16-error-response-body-format)
1818
* [1.7 DateTime Format](#17-datetime-format)
19-
* [1.8 Additional Response Object Properties](#18-additional-response-object-properties)
19+
* [1.8 Authorization](#18-authorization)
20+
+ [1.8.1 Per-Entity Authorization](#181-per-entity-authorization)
21+
+ [1.8.2 Determining Authorized Entity Actions](#182-determining-authorized-entity-actions)
22+
* [1.9 Additional Response Object Properties](#19-additional-response-object-properties)
2023
- [2. Topologies](#2-topologies)
2124
* [2.1 Topology 1 - BCF-Server only](#21-topology-1---bcf-server-only)
2225
* [2.2 Topology 2 - Colocated BCF-Server and Model Server](#22-topology-2---colocated-bcf-server-and-model-server)
@@ -35,13 +38,19 @@
3538
+ [4.1.2 GET Project Service](#412-get-project-service)
3639
+ [4.1.3 PUT Project Service](#413-put-project-service)
3740
+ [4.1.4 GET Project Extension Service](#414-get-project-extension-service)
41+
+ [4.1.5 Expressing User Authorization Through Project Extensions](#415-expressing-user-authorization-through-project-extensions)
42+
- [4.1.5.1 Project](#4151-project)
43+
- [4.1.5.2 Topic](#4152-topic)
44+
- [4.1.5.3 Comment](#4153-comment)
45+
- [4.1.5.4 Viewpoint](#4154-viewpoint)
3846
* [4.2 Topic Services](#42-topic-services)
3947
+ [4.2.1 GET Topics Service](#421-get-topics-service)
4048
+ [4.2.2 POST Topic Service](#422-post-topic-service)
4149
+ [4.2.3 GET Topic Service](#423-get-topic-service)
4250
+ [4.2.4 PUT Topic Service](#424-put-topic-service)
4351
+ [4.2.6 GET Topic BIM Snippet Service](#426-get-topic-bim-snippet-service)
4452
+ [4.2.7 PUT Topic BIM Snippet Service](#427-put-topic-bim-snippet-service)
53+
+ [4.2.8 Determining Allowed Topic Modifications](#428-determining-allowed-topic-modifications)
4554
* [4.3 File Services](#43-file-services)
4655
+ [4.3.1 GET Files (Header) Service](#431-get-files-header-service)
4756
+ [4.3.2 PUT Files (Header) Service](#432-put-files-header-service)
@@ -50,6 +59,7 @@
5059
+ [4.4.2 POST Comment Service](#442-post-comment-service)
5160
+ [4.4.3 GET Comment Service](#443-get-comment-service)
5261
+ [4.4.4 PUT Comment Service](#444-put-comment-service)
62+
+ [4.4.5 Determining allowed Comment modifications](#445-determining-allowed-comment-modifications)
5363
* [4.5 Viewpoint Services](#45-viewpoint-services)
5464
+ [4.5.1 GET Viewpoints Service](#451-get-viewpoints-service)
5565
+ [4.5.2 POST Viewpoint Service](#452-post-viewpoint-service)
@@ -59,6 +69,7 @@
5969
+ [4.5.6 PUT Viewpoint Snapshot Service](#456-put-viewpoint-snapshot-service)
6070
+ [4.5.7 GET Viewpoint Bitmap Service](#457-get-viewpoint-bitmap-service)
6171
+ [4.5.8 PUT Viewpoint Bitmap Service](#458-put-viewpoint-bitmap-service)
72+
+ [4.5.9 Determining allowed Viewpoint modifications](#459-determining-allowed-viewpoint-modifications)
6273
* [4.6 Component Services](#46-component-services)
6374
+ [4.6.1 GET Components Service](#461-get-components-service)
6475
+ [4.6.2 PUT Components Service](#462-put-components-service)
@@ -153,7 +164,65 @@ DateTime values in this API are supposed to be in ISO 8601 compliant `YYYY-MM-DD
153164

154165
For example, `2016-04-28-16:31.27+2:00` would represent _Thursday, April 28th, 2016, 16:31 (270ms) with a time zone offset of +2 hours relative to UTC._
155166

156-
## 1.8 Additional Response Object Properties
167+
## 1.8 Authorization
168+
169+
API implementors can optionally choose to restrict the actions a user is allowed to perform on the BCF entities
170+
via the API. The global default authorizations for all entities are expressed in the project extensions schema and can
171+
be locally overridden in the entities themselves.
172+
173+
### 1.8.1 Per-Entity Authorization
174+
175+
Whenever a user requests an update-able entity with the request parameter `includeAuthorization` equal to `true` the
176+
server should include an `authorization` field in the entity containing any local variations from the global
177+
authorization defaults for that entity. Using this information clients can decide whether to, for example, include an
178+
"Edit" button in the UI displaying the entity depending on the actions permitted for the user.
179+
180+
### 1.8.2 Determining Authorized Entity Actions
181+
182+
The client can calculate the available set of actions for a particular entity by taking the project-wide defaults from
183+
the project extensions, then replacing any keys defined in the entity's `authorization` map with the values specified
184+
locally. The meaning of each of the authorization keys is outlined in outlined in
185+
[4.1.5 Expressing User Authorization through Project Extensions](#415-expressing-user-authorization-through-project-extensions).
186+
187+
**Example Scenario (Topic)**
188+
189+
_In the Project Extensions_
190+
191+
{
192+
"topic_actions": [],
193+
"topic_status": [
194+
"open",
195+
"closed",
196+
"confirmed"
197+
]
198+
}
199+
200+
Indicating that by default:
201+
202+
* no modifications can be made to Topics
203+
* Topics can be placed in `open`, `closed` or `confirmed` status
204+
205+
_In the Topic_
206+
207+
{
208+
"authorization": {
209+
"topic_actions": [
210+
"update",
211+
"createComment",
212+
"createViewpoint"
213+
],
214+
"topic_status": [
215+
"closed"
216+
]
217+
}
218+
}
219+
220+
Indicating that for this topic, the current user can:
221+
222+
* update the Topic, or add comments or viewpoints
223+
* place the Topic into `closed` status
224+
225+
## 1.9 Additional Response Object Properties
157226

158227
All API response Json objects may contain additional properties that are not covered by this specification.
159228
This is to allow server implementations freedom to add additional functionality. Clients shall ignore those properties.
@@ -421,10 +490,19 @@ Retrieve a **collection** of projects where the currently logged on user has acc
421490
Body:
422491
[{
423492
"project_id": "F445F4F2-4D02-4B2A-B612-5E456BEF9137",
424-
"name": "Example project 1"
493+
"name": "Example project 1",
494+
"authorization": {
495+
"project_actions": [
496+
"createTopic",
497+
"createDocument"
498+
]
499+
}
425500
}, {
426501
"project_id": "A233FBB2-3A3B-EFF4-C123-DE22ABC8414",
427-
"name": "Example project 2"
502+
"name": "Example project 2",
503+
"authorization": {
504+
"project_actions": []
505+
}
428506
}]
429507

430508
### 4.1.2 GET Project Service
@@ -447,7 +525,13 @@ Retrieve a specific project.
447525
Body:
448526
{
449527
"project_id": "B724AAC3-5B2A-234A-D143-AE33CC18414",
450-
"name": "Example project 3"
528+
"name": "Example project 3",
529+
"authorization": {
530+
"project_actions": [
531+
"update",
532+
"updateProjectExtensions"
533+
]
534+
}
451535
}
452536

453537
### 4.1.3 PUT Project Service
@@ -474,7 +558,13 @@ Modify a specific project.
474558
Body:
475559
{
476560
"project_id": "B724AAC3-5B2A-234A-D143-AE33CC18414",
477-
"name": "Example project 3 - Second Section"
561+
"name": "Example project 3 - Second Section",
562+
"authorization": {
563+
"project_actions": [
564+
"update",
565+
"updateProjectExtensions"
566+
]
567+
}
478568
}
479569

480570
### 4.1.4 GET Project Extension Service
@@ -524,9 +614,78 @@ Project extensions are used to define possible values that can be used in topics
524614
"Architect@example.com",
525615
"BIM-Manager@example.com",
526616
"bob_heater@example.com"
617+
],
618+
"project_actions": [
619+
"update",
620+
"createTopic",
621+
"createDocument",
622+
"updateProjectExtensions"
623+
],
624+
"topic_actions": [
625+
"update",
626+
"updateBimSnippet",
627+
"updateRelatedTopics",
628+
"updateDocumentServices",
629+
"updateFiles",
630+
"createComment",
631+
"createViewpoint"
632+
],
633+
"comment_actions": [
634+
"update"
635+
],
636+
"viewpoint_actions": [
637+
"update",
638+
"updateBitmap",
639+
"updateSnapshot",
640+
"updateComponent"
527641
]
528642
}
529643

644+
### 4.1.5 Expressing User Authorization Through Project Extensions
645+
646+
Global default authorizations for the requesting user can be expressed in the project schema. The actions authorized
647+
here will apply to any entities that do not override them locally. The complete set of options for the BCF entities are
648+
listed below.
649+
650+
#### 4.1.5.1 Project
651+
652+
The 'project_actions' entry in the project extensions defines what actions are allowed to be performed
653+
at the project level. The available actions include:
654+
655+
* *update* - The ability to update the project details (see [4.1.3 PUT Project Service](#413-put-project-service))
656+
* *createTopic* - The ability to create a new topic (see [4.2.2 POST Topic Service](#422-post-topic-service))
657+
* *createDocument* - The ability to create a new document (see [4.9.2 POST Document Service](#492-post-document-service))
658+
659+
#### 4.1.5.2 Topic
660+
661+
The 'topic_actions' entry in the project extensions defines what actions are allowed to be performed at the topic
662+
level by default (i.e. unless overridden by specific topics) The available actions include:
663+
664+
* *update* - The ability to update the topic (see [4.2.4 PUT Topic Service](#424-put-topic-service))
665+
* *updateBimSnippet* - The ability to update the BIM snippet for topics (see [4.2.7 PUT Topic BIM Snippet Service](#427-put-topic-bim-snippet-service))
666+
* *updateRelatedTopics* - The ability to update the collection of related topics (see [4.7.2 PUT Related Topics Service](#472-put-related-topics-service))
667+
* *updateDocumentReferences* - The ability to update the collection of document references (see [4.8.3 PUT Document Reference Service](#483-put-document-reference-service))
668+
* *updateFiles* - The ability to update the file header (see [4.3.2 PUT Files (Header) Service](#432-put-files-header-service))
669+
* *createComment* - The ability to create a comment (see [4.4.2 POST Comment Service](#442-post-comment-service))
670+
* *createViewpoint* - The ability to create a new viewpoint (see [4.5.2 POST Viewpoint Service](#452-post-viewpoint-service))
671+
672+
#### 4.1.5.3 Comment
673+
674+
The 'comment_actions' entry in the project extensions defines what actions are allowed to be performed at the comment level by
675+
default (i.e unless overridden by specific comments). The available actions include:
676+
677+
* *update* - The ability to update the comment (see [4.4.4 PUT Comment Service](#444-put-comment-service))
678+
679+
#### 4.1.5.4 Viewpoint
680+
681+
The 'viewpoint_actions' entry in the project extensions defines what actions are allowed to be performed at the viewpoint level by
682+
default (i.e. unless overridden by specific viewpoints). The available actions include:
683+
684+
* *update* - The ability to update the viewpoint (see [4.5.4 PUT Viewpoint Service](#454-put-viewpoint-service))
685+
* *updateBitmap* - The ability to update the bitmap for the viewpoint (see [4.5.8 PUT Viewpoint Bitmap Service](#458-put-viewpoint-bitmap-service))
686+
* *updateSnapshot* - The ability to update the snapshot for the viewpoint (see [4.5.6 PUT Viewpoint Snapshot Service](#456-put-viewpoint-snapshot-service))
687+
* *updateComponent* - The ability to update the component for the viewpoint (see [4.6.2 PUT Components Service](#462-put-components-service))
688+
530689
---------
531690

532691
## 4.2 Topic Services
@@ -718,6 +877,12 @@ Retrieve a specific topic.
718877
"is_external": true,
719878
"reference": "https://example.com/bcf/1.0/ADFE23AA11BCFF444122BB",
720879
"reference_schema": "https://example.com/bcf/1.0/clash.xsd"
880+
},
881+
"authorization": {
882+
"topic_actions": [
883+
"createComment",
884+
"createViewpoint"
885+
]
721886
}
722887
}
723888

@@ -797,6 +962,12 @@ Retrieves a topics BIM-Snippet as binary file.
797962

798963
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.
799964

965+
### 4.2.8 Determining Allowed Topic Modifications
966+
967+
The global default Topic authorizations are expressed in the project schema and when Topic(s) are requested with the
968+
parameter "includeAuthorization" equal to "true" Topics will include an "authorization" field containing any local
969+
overrides for each Topic.
970+
800971
## 4.3 File Services
801972

802973
### 4.3.1 GET Files (Header) Service
@@ -910,7 +1081,12 @@ Get comments that are closed and created after December 5 2015. Sort the result
9101081
"date": "2016-08-01T12:34:22.409Z",
9111082
"author": "max.muster@example.com",
9121083
"comment": "Clash found",
913-
"topic_guid": "B345F4F2-3A04-B43B-A713-5E456BEF8228"
1084+
"topic_guid": "B345F4F2-3A04-B43B-A713-5E456BEF8228",
1085+
"authorization": {
1086+
"comment_actions": [
1087+
"update"
1088+
]
1089+
}
9141090
}, {
9151091
"guid": "A333FCA8-1A31-CAAC-A321-BB33ABC8414",
9161092
"date": "2016-08-01T14:24:11.316Z",
@@ -1003,6 +1179,7 @@ Update a single comment, description similar to POST.
10031179
"comment": "will rework the heating model and fix the ventilation"
10041180
}
10051181

1182+
10061183
**Example Response**
10071184

10081185
Response Code: 200 - OK
@@ -1017,6 +1194,12 @@ Update a single comment, description similar to POST.
10171194
"topic_guid": "B345F4F2-3A04-B43B-A713-5E456BEF8228"
10181195
}
10191196

1197+
### 4.4.5 Determining allowed Comment modifications
1198+
1199+
The global default Comment authorizations are expressed in the project schema and when Comment(s) are requested with the
1200+
parameter "includeAuthorization" equal to "true" Comments will include an "authorization" field containing any local
1201+
overrides for each Comment.
1202+
10201203
## 4.5 Viewpoint Services
10211204

10221205
### 4.5.1 GET Viewpoints Service
@@ -1084,6 +1267,14 @@ Retrieve a **collection** of all viewpoints related to a topic.
10841267
"z": 0.1
10851268
}
10861269
}]
1270+
},
1271+
"authorization": {
1272+
"viewpoint_actions": [
1273+
"update",
1274+
"updateBitmap",
1275+
"updateSnapshot",
1276+
"updateComponent"
1277+
]
10871278
}
10881279
}, {
10891280
"guid": "a11a82e7-e66c-34b4-ada1-5846abf39133",
@@ -1132,8 +1323,12 @@ Retrieve a **collection** of all viewpoints related to a topic.
11321323
"z": 0.0
11331324
}
11341325
}]
1326+
},
1327+
"authorization": {
1328+
"viewpoint_actions": []
11351329
}
11361330
}]
1331+
11371332
### 4.5.2 POST Viewpoint Service
11381333

11391334
**Resource URL**
@@ -1347,6 +1542,14 @@ Retrieve a specific viewpoint.
13471542
"z": 0.0
13481543
}
13491544
}]
1545+
},
1546+
"authorization": {
1547+
"viewpoint_actions": [
1548+
"update",
1549+
"updateBitmap",
1550+
"updateSnapshot",
1551+
"updateComponent"
1552+
]
13501553
}
13511554
}
13521555

@@ -1497,10 +1700,15 @@ PUT Body contains binary image data
14971700

14981701
**Example Response**
14991702

1500-
15011703
Response Code: 200 - OK
15021704
Empty Body
15031705

1706+
### 4.5.9 Determining allowed Viewpoint modifications
1707+
1708+
The global default Viewpoint authorizations are expressed in the project schema and when Viewpoint(s) are requested with the
1709+
parameter "includeAuthorization" equal to "true" Viewpoints will include an "authorization" field containing any local
1710+
overrides for each Viewpoint.
1711+
15041712
## 4.6 Component Services
15051713

15061714
### 4.6.1 GET Components Service
@@ -1799,4 +2007,4 @@ Retrieves a document as binary file.
17992007

18002008
**Example Response**
18012009

1802-
Retrieves a document as binary file.
2010+
Retrieves a document as binary file.

‎Schemas_draft-03/Collaboration/Comment/comment_GET.json‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,19 @@
3737
"modified_author": {
3838
"type": ["string",
3939
"null"]
40+
},
41+
"authorization": {
42+
"type": "object",
43+
"required": false,
44+
"properties": {
45+
"comment_actions": {
46+
"required": false,
47+
"type": "array",
48+
"items": {
49+
"enum": ["update"]
50+
}
51+
}
52+
}
4053
}
4154
}
4255
}

0 commit comments

Comments
 (0)