16 |
--------------------------------------------------------------------------------
/Documentation/bSDD API.md:
--------------------------------------------------------------------------------
1 | ## The bSDD API
2 | The bSDD API offers methods to retrieve `Class` and `Property` information of many dictionaries (standards) like IFC and ETIM. An example flow is:
3 | * User opens screen to search for a Class and its Properties
4 | * After opening screen the app calls the “Dictionary”-method of the API to retrieve a list of available Dictionaries. This list can then be presented to the user to make a selection.
5 | * The user selects a Dictionary and enters some text to find the required Class
6 | * The user presses Search, and the app sends the request to the bSDD API (“SearchList”-method)
7 | * The result is a list of Classes
8 | * The user can pick the one needed
9 | * The app sends a request for Class details and Properties to the bSDD API (“Class”-method)
10 | * The API returns Class details and Properties, which the app shows to the user
11 |
12 | A typical use case is demonstrated in SketchUp. A video of the SketchUp use-case and bSDD plugin is available at https://vimeo.com/446417661/ff8b6605d3
13 |
14 | **The bSDD API is regularly updated.** If there are breaking changes to the API, we create a new version and support both versions for 6 months after the change occurred. Additions to an existing API usually don't mean a breaking change and can be introduced to the same version.
15 |
16 | ## API contracts and testing the API
17 | You can get the API contract information at [bSDD API contract, official release](https://app.swaggerhub.com/apis/buildingSMART/Dictionaries/v1) or [bSDD API contract, test](https://test.bsdd.buildingsmart.org/swagger). This information is available without the need for you to log in. You can also test the API methods. Secured methods are marked with a lock. To access secured methods, you need to log in via the UI by using the Authorize button:
18 |
19 | 
20 |
21 | Don’t forget to check the “read” scope!
22 |
23 | ## Using https://identifier.buildingsmart.org
24 | You can access the data of the `Class` or `Property` also directly via the URI of the `Class` or `Property`. For example, you can navigate in the browser to https://identifier.buildingsmart.org/uri/buildingsmart/ifc/4.3/class/IfcWall, and then you will see a visual representation of the data of that Class. If you would like the output in JSON format, then sending an "Accept" header with "application/JSON" will give you a result in JSON. The content of this JSON result differs from the HTML result!
25 |
26 | IMPORTANT: Do not use these identifier URIs for system-to-system communication! First of all, it introduces an extra 'hop' from server to server. Second, you do not have control over the version of the API it's using. The result may differ after a new release of bSDD has been published with the result from before the release.
27 |
28 | > Note: Getting the data in JSON format by directly calling the https://identifier.buildingsmart.org URL is now DEPRECATED. Use api/Class/vX or api/Property/vX instead.
29 |
30 | ## bSDD test environment
31 |
32 | The bSDD has a TEST environment for testing new developments of the bSDD. Although meant for internal use, developers wanting to use the bSDD APIs are welcome to use the TEST environment for development purposes. We do not have an SLA for that environment and we don't recommend showing its content to users. If you're a Dictionary owner and want to check your data or test the upload process, please use the official bSDD.
33 |
34 | ## GraphQL
35 | The data can also be accessed via GraphQL. You can try it out here:
36 | [GraphiQL TEST playground](https://test.bsdd.buildingsmart.org/graphiql).
37 |
38 |
39 | The URL to send GraphQL requests to is:
40 | - official release: https://api.bsdd.buildingsmart.org/graphqls (secured, note the "s" at the end)
41 | - test version: https://test.bsdd.buildingsmart.org/graphql (not secured)
42 | - test version: https://test.bsdd.buildingsmart.org/graphqls (secured)
43 | Note: those URLs are not hyperlinks and do not work in a browser. You need to send a POST request with the query data (the GET request does not work).
44 |
45 | Here you can find an example code for accessing a secured bSDD API: [bSDD GraphQL examples](https://github.com/buildingSMART/bSDD/blob/master/Documentation/bSDD%20and%20GraphQL.md). Contact us if you need assistance implementing this.
46 |
47 | ## For client developers
48 |
49 | ### Http header "(X-)User-Agent"
50 | Please include your application's name and version in the HTTP header "User-Agent" (or "X-User-Agent") for each HTTP call. This will allow us to better track bSDD usage and provide you with some statistics regarding your application using the bSDD API. The preferred format is "application/version," e.g., "Autodesk.Revit/2024.".
51 |
52 | ### Secure APIs
53 | If you are going to build a client that uses secured APIs, you must request a Client ID. You can do so by sending us an email and give:
54 | - the name of the client application
55 | - type of application:
56 | - Web application
57 | - Single-page application
58 | - iOS / macOS, Objective-C, Swift, Xamarin
59 | - Android - Java, Kotlin, Xamarin
60 | - Mobile/Desktop
61 | - which language are you using? (sometimes the redirectUri to be configured depends on the used library)
62 | - if it is a website or SPA, specify the return URL (the login page will redirect to this URL after the user has logged in)
63 |
64 | If you don't use the secured APIs but want to call the other APIs from your website or SPA, we need your website's URL to allow CORS.
65 | If you're creating a desktop client that only calls the non-secured APIs, you're ready to go.
66 |
67 | ### Authentication
68 | For authentication, we use Azure Active Directory B2C.
69 | At this moment, you need to authenticate only a few methods. This might change.
70 |
71 | If you’re developing a Javascript, Java, Angular, React, Python, or .NET application, connecting with the buildingSMART Data Dictionary API is easiest if you use the Microsoft Authentication Library (MSAL).
72 | See [Active directory B2C code samples](https://docs.microsoft.com/en-us/azure/active-directory-b2c/code-samples) for ready-to-use examples on how to use the MSAL. You can find the bSDD API-specific settings in one of the next sections of this document. Make sure you have the settings in an easy-to-update settings file.
73 | You can find the code for a small .NET console application that accesses the bSDD API (authenticated) in this repository: [.NET console example](https://github.com/buildingSMART/bSDD/tree/master/Source%20code%20examples/CSharp-Client-Console-Demo).
74 |
75 | React: https://docs.microsoft.com/en-us/azure/active-directory/develop/tutorial-v2-react
76 | https://github.com/Azure-Samples/ms-identity-javascript-react-tutorial/blob/main/1-Authentication/2-sign-in-b2c/README.md
77 | Angular: https://docs.microsoft.com/en-us/azure/active-directory/develop/tutorial-v2-angular-auth-code
78 | Java: https://docs.microsoft.com/en-us/samples/azure-samples/ms-identity-java-webapp/ms-identity-java-webapp/
79 | Python: https://docs.microsoft.com/en-us/python/api/overview/azure/active-directory
80 |
81 | If you're developing using other languages, you can still connect to the bSDD API as the API is according to the standards OpenAPI, OAuth2, and OpenID Connect.
82 |
83 | To access a secured API, a user must first register themself. When you’re using MSAL, there’s nothing special you need to do for this. The user will be prompted to log in via a browser window. If the user does not have a buildingSMART API account, he can sign up:
84 |
85 | 
86 |
87 | The user will be registered in the buildingSMART Azure B2C Active Directory.
88 | Currently there’s no further authorization required to be able to use the API.
89 |
90 | ### Settings
91 | These are the settings you can use for demonstration purposes for a Dekstop client app :
92 | * Tenant: "buildingsmartservices.onmicrosoft.com"
93 | * AzureAdB2Chostname: "authentication.buildingsmart.org"
94 | * ClientId: "4aba821f-d4ff-498b-a462-c2837dbbba70"
95 | * RedirectUri: "com.onmicrosoft.bsddprototypeb2c.democonsoleapp://oauth/redirect"
96 | * PolicySignUpSignIn: "b2c_1a_signupsignin_c"
97 | * PolicyEditProfile: "b2c_1a_profileedit_c"
98 | * PolicyResetPassword: "b2c_1a_passwordreset_c"
99 |
100 | * ApiScope : "https://buildingsmartservices.onmicrosoft.com/api/read"
101 | * BsddApiUrl: "https://test.bsdd.buildingsmart.org"
102 |
103 | The full B2C authority URL is: https://authentication.buildingsmart.org/tfp/buildingsmartservices.onmicrosoft.com/b2c_1a_signupsignin_c (note the "tfp" part!).
104 |
105 | For using the official release, you should use the settings as above except:
106 | * ClientId: request a Client ID using [CONTACT FORM](https://share.hsforms.com/1RtgbtGyIQpCd7Cdwt2l67A2wx5h)
107 | * RedirectUri: let us know what kind of app you are making and with which technology
108 | * ApiScope : "https://buildingsmartservices.onmicrosoft.com/bsddapi/read"
109 | * BsddApiUrl: "https://api.bsdd.buildingsmart.org"
110 |
111 |
112 | If you are developing a Web App that’s going to use the bSDD API, let us know ([CONTACT FORM](https://share.hsforms.com/1RtgbtGyIQpCd7Cdwt2l67A2wx5h)). The RedirectURI needs to be configured in Azure AD.
113 |
114 | ### Additional information
115 | Language-independent description of the authorization flow: [Authorization code flow](https://docs.microsoft.com/en-us/azure/active-directory-b2c/authorization-code-flow)
116 |
117 | High-level descriptions of the various authentication flows: [AD B2C application types](https://docs.microsoft.com/en-us/azure/active-directory-b2c/application-types)
118 |
119 | Oauth2 and OpenId protocol descriptions: [AD B2C protocols overview](https://docs.microsoft.com/en-us/azure/active-directory-b2c/protocols-overview)
120 |
121 |
--------------------------------------------------------------------------------
/Documentation/bSDD and GraphQL.md:
--------------------------------------------------------------------------------
1 | # bSDD and GraphQL
2 |
3 | ## Notification
4 |
5 | We've applied several changes in naming:
6 |
7 | 1. "Domain" --> "Dictionary"
8 | 2. "Classification" --> "Class"
9 | 3. "NamespaceUri" --> "Uri"
10 | 4. "IncludeChilds" --> "IncludeChildren"
11 |
12 | To be consistent, names in our GraphQL API have also been changed.
13 | But we do support the old naming until at least April 2024.
14 |
15 | ## Short intro on GraphQL
16 |
17 | A 'regular' API is quite static: you do a request and it returns a predefined set of data. If you need some more info you probably need to do another API call. And then maybe another call until you have got all the data you want. GraphQL is designed to overcome that issue: it is a query language with which you can specify the data you need.
18 |
19 | For more info on GraphQL have a look at, for example:
20 | - https://dev.to/davinc/graphql-for-beginners-3f1a
21 | - https://www.freecodecamp.org/news/a-beginners-guide-to-graphql-60e43b0a41f5/
22 |
23 | For some scenario's using GraphQL can be more efficient, but there are still lots of scenario's where a regular API is the most efficient solution.
24 |
25 | ## bSDD GraphQL endpoints
26 |
27 | The bSDD API also provides a GraphQL endpoint and the test environment also has a playground:
28 |
29 | Playground: https://test.bsdd.buildingsmart.org/graphiql/
30 | Test GraphQL endpoint: https://test.bsdd.buildingsmart.org/graphql/
31 | Test GraphQL secured endpoint: https://test.bsdd.buildingsmart.org/graphqls/
32 |
33 | Production GraphQL secured endpoint: https://api.bsdd.buildingsmart.org/graphqls/
34 |
35 | See document https://github.com/buildingSMART/bSDD/blob/master/Documentation/bSDD%20API.md for info how to access secured APIs. For accessing the secured GraphQL endpoint it is the same.
36 |
37 | ## Example data queries
38 |
39 | -- get the list of available languages:
40 | ```
41 | {
42 | languages {
43 | isocode
44 | }
45 | }
46 | ```
47 | ----
48 |
49 | -- get list of country codes:
50 | ```
51 | {
52 | countries {
53 | code
54 | }
55 | }
56 | ```
57 | ----
58 |
59 | You can combine those queries into one:
60 | ```
61 | {
62 | languages {
63 | isocode
64 | }
65 |
66 | countries {
67 | code
68 | }
69 | }
70 | ```
71 | ----
72 |
73 | -- search for classes within a dictionary:
74 | ```
75 | {
76 | dictionary(uri : "https://identifier.buildingsmart.org/uri/sbe/swedishmaterials/1") {
77 | uri
78 | copyrightNotice
79 | languageCode
80 | classSearch(searchText: "asfaltbetong", languageCode: "sv-SE") {
81 | name
82 | uri
83 | synonyms
84 | relatedIfcEntityNames
85 | properties {
86 | name
87 | isRequired
88 | pattern
89 | }
90 | }
91 | }
92 | }
93 | ```
94 | ----
95 |
96 | -- get all classes with their properties of a dictionary:
97 |
98 | ATTENTION: this query will take a long time to execute for dictionaries with many classes
99 | ```
100 | {
101 | dictionary(uri : "https://identifier.buildingsmart.org/uri/bs-agri/fruitvegs/1.0") {
102 | name
103 | version
104 | uri
105 | copyrightNotice
106 | languageCode
107 | status
108 | releaseDate
109 | license
110 | licenseUrl
111 | moreInfoUrl
112 |
113 | classSearch {
114 | code
115 | name
116 | uri
117 | definition
118 | documentReference
119 | synonyms
120 | relatedIfcEntityNames
121 | properties {
122 | code
123 | name
124 | uri
125 | description
126 | definition
127 | documentReference
128 | isRequired
129 | dataType
130 | example
131 | dimension
132 | physicalQuantity
133 | pattern
134 | allowedValues {
135 | code
136 | value
137 | }
138 | units
139 | }
140 | }
141 | }
142 | }
143 | ```
144 | ----
145 |
146 | -- get details for a class, using variables:
147 | ```
148 | query ($dictionaryUri: String!, $uri: String!) {
149 | dictionary(uri: $dictionaryUri) {
150 | name
151 | uri
152 | class(uri: $uri, includeChildren: true) {
153 | activationDateUtc
154 | childs {
155 | name
156 | uri
157 | }
158 | classType
159 | code
160 | countriesOfUse
161 | countryOfOrigin
162 | creatorLanguageCode
163 | deActivationDateUtc
164 | definition
165 | deprecationExplanation
166 | documentReference
167 | name
168 | uri
169 | properties {
170 | name
171 | uri
172 | }
173 | relatedIfcEntityNames
174 | relations {
175 | relatedClassName
176 | relatedClassUri
177 | relationType
178 | }
179 | replacedObjectCodes
180 | replacingObjectCodes
181 | revisionDateUtc
182 | status
183 | subdivisionsOfUse
184 | synonyms
185 | uid
186 | versionDateUtc
187 | versionNumber
188 | visualRepresentationUri
189 | }
190 | }
191 | }
192 | ```
193 | The query variable section defines the variables:
194 | ```
195 | {
196 | "dictionaryUri": "https://identifier.buildingsmart.org/uri/sbe/swedishmaterials/1",
197 | "uri": "https://identifier.buildingsmart.org/uri/sbe/swedishmaterials/1/class/ACDE"
198 | }
199 | ```
200 | ## Example meta data queries
201 |
202 | In GraphQL you can also execute queries on the GraphQL schema (also known as "Introspection"). You can use that to get, for example, the available fields or queries:
203 | ```
204 | {
205 | __schema {
206 | types {
207 | name
208 | fields {
209 | name
210 | description
211 | }
212 | }
213 | }
214 | }
215 |
216 | query availableQueries {
217 | __schema {
218 | queryType {
219 | fields {
220 | name
221 | description
222 | type {
223 | kind
224 | name
225 | fields {
226 | name
227 | description
228 | }
229 | }
230 | }
231 | }
232 | }
233 | }
234 | ```
235 | More examples of Introspection can be found at: https://graphql.org/learn/introspection/
--------------------------------------------------------------------------------
/Documentation/bSDD import tutorial.md:
--------------------------------------------------------------------------------
1 | In this tutorial, we explain how to publish and manage bSDD content using [the bSDD Manage portal](https://manage.bsdd.buildingsmart.org/).
2 |
3 | ## Publishing the first dictionary
4 |
5 | 
46 |
47 | You have the option to first validate if the file is free of errors or upload it for testing by selecting option 'Test upload'. The test upload means the content will be automatically deleted from bSDD after 2 months and it will not be possible to set the status to 'Active' to prevent mistakes.
48 |
49 | > Note: If you only want to experiment with the bSDD, we provide an option for a `TEST` upload. This is a safe option for beginners, as the content uploaded as a `TEST` cannot be activated and will automatically be removed after 2 months.
50 |
51 | Press "Upload selected file"
52 |
53 | Before each import, we recommend first using the option 'Validate only?' This will inform you of any errors or warnings without trying to import the file.
54 |
55 | **Important** Uploading a new file with the same version number as already existing will replace the content (only if status is `Preview`, as all other content is immutable - [read more below](#the-lifecycle-of-a-dictionary)).
56 |
57 | Once ready, and if the platform returns no errors, click "Upload selected file."
58 |
59 | Once the file has been imported, you will receive a more detailed import report by email. It might take up to 15 minutes. If the import routine spots any errors, you will see them listed in the email.
60 |
61 | **Important** Uploading will make the content publicly available. Do not publish anything that you don't want to share with the general public, or you don't have sufficient permission.
62 |
63 | > Note: it is possible to restrict the visibility of a dictionary only to certain users. However, this is a paid feature of bSDD. Read more about [Private dictionaries](https://technical.buildingsmart.org/services/bsdd/private-dictionaries/).
64 |
65 | > Note: all of the steps explained above can also be automated using 
72 |
73 | **⚠️ Once the content is activated, it will get an immutable URI, meaning the content will stay in bSDD permanently and can't be deleted.** It is still possible to change the status to `Inactive`, indicating it should no longer be used, but the page will still exist and show the content. Consider that before activating the version of a dictionary.
74 |
75 | 
6 |
7 | **The buildingSMART Data Dictionary (bSDD)** is an online service for hosting data dictionaries containing classifications, their properties, allowed values, units, translations, etc. It provides a standardized workflow to improve data quality and information consistency.
8 |
9 | Read more at bSDD project page: https://www.buildingsmart.org/users/services/buildingsmart-data-dictionary/
10 |
11 | ### Overview
12 |
13 | At the heart of bSDD is a canonical database, where all dictionaries can be related to each other. The main way to access the bSDD is through its [APIs (Application Programming Interfaces)](https://app.swaggerhub.com/apis/buildingSMART/Dictionaries/v1). This is how most BIM software and other apps can use the data stored in the bSDD. Apart from that, there is [the bSDD Search page](https://search.bsdd.buildingsmart.org/), where people can look up the content. Authors can publish content to bSDD through [the API](https://app.swaggerhub.com/apis/buildingSMART/Dictionaries/v1) or [the bSDD Manage portal](https://manage.bsdd.buildingsmart.org/). To upload, please register your organisation using [the organisation registration form](https://bsi-technicalservices.atlassian.net/servicedesk/customer/portal/3/group/4/create/25).
14 |
15 | Get list of domains
37 | 42 |