Version 0.1 based on BCF API v2.1. BCF API GitHub repository
Table of Contents
- 1. Introduction
- 2. Public Services
This is
When requesting collections of items, a BSI API Server should offer URL parameters according to the OData v4 specification. It can be found at http://www.odata.org/documentation/.
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 http://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.
This means that there is no partial update mechanism for objects but every PUT request is sending the whole object representation. PUT schemas may exclude server generated values that cannot be edited, such as creation dates or authors.
To work with browser based API clients using Cross Origin Resource Sharing (Cors), servers will put the Access-Control-Allow' headers in the response headers and specifiy who can access the servers Json resources. The client can look for these values and proceed with accessing the resources.
In a CORS scenario, web clients expect the following headers:
Access-Control-Allow-Headers: Authorization, Content-Type, Acceptto allow theAuthorization,Content-TypeandAcceptheaders to be used via XHR requestsAccess-Control-Allow-Methods: GET, POST, PUT, OPTIONSto allow the Http methods the API needsAccess-Control-Allow-Origin: example.comto allow XHR requests from theexample.comdomain to the BSI API server
For example, Asp.Net applications in IIS need the following entries in their web.config file. * means the server allows any values.
<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>
The BSI APIs rely on the regular Http Status Code definitions. Good sources are Wikipedia or the HTTP/1.1 Specification.
Generally, these response codes shall be used in the API:
200 - OKforGETrequests that return data orPUTrequests that update data201 - CreatedforPOSTrequests that create data
POST and PUT requests do usually include the created resource in the response body. Exceptions to this rule are described in the specific section for the resource.
BCI APIs have a specified error response body format error.json.
DateTime values in this API are supposed to be in ISO 8601 compliant YYYY-MM-DDThh:mm:ss format with optional time zone indicators. This is the same format as defined in the Xml xs:dateTime type as well as the result of JavaScripts Date.toJson() output.
For example, 2016-04-28T16:31:12.270+02:00 would represent Thursday, April 28th, 2016, 16:31:12 (270ms) with a time zone offset of +2 hours relative to UTC.
Please note that the colon in the timezone offset is optional, so +02:00 is equivalent to +0200.
API implementors can optionally choose to restrict the actions a user is allowed to perform on the applicable entities via the API. The global default authorizations for all entities are expressed in the project extensions schema and can be locally overridden in the entities themselves.
Whenever a user requests an update-able entity with the query parameter includeAuthorization equal to true the
server should include an authorization field in the entity containing any local variations from the global
authorization defaults for that entity. Using this information clients can decide whether to, for example, include an
"Edit" button in the UI displaying the entity depending on the actions permitted for the user.
The client can calculate the available set of actions for a particular entity by taking the project-wide defaults from
the project extensions, then replacing any keys defined in the entity's authorization map with the values specified
locally. The meaning of each of the authorization keys is outlined in outlined in
4.1.5 Expressing User Authorization through Project Extensions.
Example Scenario (Topic)
In the Project Extensions
{
"topic_actions": [],
"topic_status": [
"open",
"closed",
"confirmed"
]
}
Indicating that by default:
- no modifications can be made to Topics
- Topics can be placed in
open,closedorconfirmedstatus
In the Topic
{
"authorization": {
"topic_actions": [
"update",
"createComment",
"createViewpoint"
],
"topic_status": [
"closed"
]
}
}
Indicating that for this topic, the current user can:
- update the Topic, or add comments or viewpoints
- place the Topic into
closedstatus
All API response and request Json objects may contain additional properties that are not covered by this specification. This is to allow server and client implementations freedom to add additional functionality. Servers and clients shall ignore those properties and must not produces errors on additional properties. Servers and clients are not required to preserve these properties.
Some endpoints in the BSI APIs may expect binary file uploads, such as the BCF Document Service and the BCF BIM Snippet Service.
In such cases, files should be sent with the following Http headers:
Headers:
Content-Type: application/octet-stream;
Content-Length: {Size of file in bytes};
Content-Disposition: attachment; filename="{Filename.extension}";
Resource URL (public resource)
GET /bsi/versions
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| api_id | string | Identifier of the API | true |
| version_id | string | Identifier of the version | true |
| detailed_version | string | Url to specification on GitHub | false |
Returns a list of all supported BSI API versions of the server.
Example Request
GET /bsi/versions
Example Response
Response Code: 200 - OK
Body:
{
"versions": [{
"api_id": "bsi-foundations",
"version_id": "0.1",
"detailed_version": "https://github.com/BuildingSMART/BSI-FOUNDATIONS"
}, {
"api_id": "bcf",
"version_id": "2.1",
"detailed_version": "https://github.com/BuildingSMART/BCF-API"
}]
}
Authentication is based on the OAuth 2.0 Protocol.
Resource URL (public resource)
GET /bsi/{version}/auth
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| oauth2_auth_url | string | URL to authorization page (used for Authorization Code Grant and Implicit Grant OAuth2 flows) | false |
| oauth2_token_url | string | URL for token requests | false |
| oauth2_dynamic_client_reg_url | string | URL for automated client registration | false |
| http_basic_supported | boolean | Indicates if Http Basic Authentication is supported | false |
| supported_oauth2_flows | string[] | array of supported OAuth2 flows |
If oauth2_auth_url is present, then oauth2_token_url must also be present and vice versa. If properties are not present in the response, clients should assume that the functionality is not supported by the server, e.g. a missing http_basic_supported property would indicate that Http basic authentication is not available on the server.
OAuth2 flows are described in detail in the OAuth2 specification. BSI API servers may support the following workflows:
authorization_code_grant- 4.1 - Authorization Code Grantimplicit_grant- 4.2 - Implicit Grantresource_owner_password_credentials_grant- 4.3 - Resource Owner Password Credentials Grant
The OAuth2 Client Credentials Grant (section 4.4) is not supported since it does not contain any user identity. Also the Extension Grants (section 4.5) are not supported.
Example Request
GET /bsi/0.1/auth
Example Response
Response Code: 200 - OK
Body:
{
"oauth2_auth_url": "https://example.com/bsi/oauth2/auth",
"oauth2_token_url": "https://example.com/bsi/oauth2/token",
"oauth2_dynamic_client_reg_url": "https://example.com/bsi/oauth2/reg",
"http_basic_supported": true,
"supported_oauth2_flows": [
"authorization_code_grant",
"implicit_grant",
"resource_owner_password_credentials_grant"
]
}
An example for the OAuth2 Authorization Grant workflow can be found here.
The following part describes the optional dynamic registration process of a client. BSI API Servers may offer additional processes registering clients, for example allowing a client application developer to register his client on the servers website.
The resource url for this service is server specific and is returned as oauth2_dynamic_client_reg_url in the GET /bsi/{version}/auth resource.
Register a new client :
Parameters
JSON encoded body using the application/json content type.
| parameter | type | description |
|---|---|---|
| client_name | string (max. length 60) | The client name |
| client_description | string (max. length 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
POST https://example.com/bsi/oauth2/reg
Body:
{
"client_name": "Example Application",
"client_description": "Example CAD desktop application",
"client_url": "http://example.com",
"redirect_url": "http://localhost:8080"
}
Example Response
Response Code: 201 - Created
Body:
{
"client_id": "cGxlYXN1cmUu",
"client_secret": "ZWFzdXJlLg=="
}
Resource URL
GET /bsi/{version}/current-user
Example Request
GET /bsi/0.1/current-user
Example Response
Response Code: 200 - OK
Body:
{
"id": "Architect@example.com",
"name": "John Doe"
}