/shared-common-API

Shared elements in the diverse API standards

Official repository by buildingSMART International This repo is managed by the Open CDE APIs Implementers Group

Open CDE Foundation API

Version 1.0 based on BCF API v2.1. BCF API GitHub repository

Table of Contents

1. Introduction

The Open CDE Foundation API includes a small number of services and a few conventions that are common to all Open CDE APIs.

1.1 Paging, Sorting and Filtering

When requesting collections of items, the Server should offer URL parameters according to the OData v4 specification. It can be found at http://www.odata.org/documentation/.

1.2 Caching

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.

1.3 Updating Resources via HTTP PUT

Whenever a resource offers the HTTP PUT method, it is 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.

1.4 Cross Origin Resource Sharing (CORS)

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 specify 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, Accept to allow the Authorization, Content-Type and Accept headers to be used via XHR requests
  • Access-Control-Allow-Methods: GET, POST, PUT, OPTIONS to allow the Http methods the API needs
  • Access-Control-Allow-Origin: example.com to allow XHR requests from the example.com domain to the 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>

1.5 Http Status Codes

Web-based 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 - OK for GET requests that return data or PUT requests that update data
  • 201 - Created for POST requests that create data
  • 403 - Forbidden for requests that can't be fulfilled because the user is not authorized to perform them

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.

1.6 Error Response Body Format

All Open CDE APIs have a specified error response body format error.json.

1.7 DateTime Format

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.

To void ambiguity, This specification steps away from ISO 8601 on the topic of DateTime values with no timezone: The ISO 8601 says that DateTime values with no timezone designator are local times - **In BCF all DateTime values with no timezone designator are assumed to be in UTC.Therefore, adding a timezone designator is highly recommended. **.

1.8 Additional Response and Request Object Properties

All API response and request JSON objects may contain additional properties that are not part of the specified exchange for that endpoint. This is to allow server and client implementations freedom to add additional functionality. Servers and clients shall ignore those properties and must not produce errors on additional properties. Servers and clients are not required to preserve these properties.

1.9 Binary File Uploads

Some endpoints 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}";

1.10 Differences Between null and Empty Lists

Some array or list properties and responses can be interpreted differently if they are either null or empty. In general, there are two cases to consider.

For collection resources:

  • A collection resource that does not exist should return Http error 404 - Not Found, e.g. the list of topics for an invalid project id.
  • If the resource exists but there are no elements, the returned response should be an empty array [], e.g. the list of topics for a project where no topics exist.

For properties:

  • If a list property is null (by explicitly setting it to null or not returning it in the response object at all), the client should not assume that this represents an empty list but instead the property is not present on the response object. Depending on the response object, this can have the same meaning as an empty list (e.g. no components in a viewpoint is the same as an empty list of components), but this can also mean the property is just omitted for optional properties (e.g. no topic_actions in an authorization object can mean no restrictions).

2. Public Services

2.1 Versions Service

versions_GET.json

Resource URL (public resource)

GET /opencde/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 Open CDE APIs and their versions.

Example Request

GET /opencde/versions

Example Response

Response Code: 200 - OK
Body:
{
    "versions": [{
        "api_id": "open-cde-foundation",
        "version_id": "1.0",
        "detailed_version": "https://github.com/BuildingSMART/shared-common-API/tree/v1.0"
    }, {
        "api_id": "bcf",
        "version_id": "2.1",
        "detailed_version": "https://github.com/buildingSMART/BCF-API/tree/v2.1"
    }, {
        "api_id": "bcf",
        "version_id": "2.2",
        "detailed_version": "https://github.com/buildingSMART/BCF-API/tree/v2.2"
    }]
}

2.2 Authentication Services

2.2.1 Obtaining Authentication Information

auth_GET.json

Authentication is based on the OAuth 2.0 Protocol.

Resource URL (public resource)

GET /opencde/{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. Open CDE API servers may support the following flows:

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 /opencde/1.0/auth

Example Response

Response Code: 200 - OK
Body:
{
    "oauth2_auth_url": "https://example.com/opencde/oauth2/auth",
    "oauth2_token_url": "https://example.com/opencde/oauth2/token",
    "oauth2_dynamic_client_reg_url": "https://example.com/opencde/oauth2/reg",
    "http_basic_supported": true,
    "supported_oauth2_flows": [
        "authorization_code_grant",
        "implicit_grant",
        "resource_owner_password_credentials_grant"
    ]
}

2.2.2 OAuth2 Example

An example for the OAuth2 Authorization Grant workflow can be found here.

2.2.3 OAuth2 Protocol Flow - Dynamic Client Registration

dynRegClient_POST.json

dynRegClient_GET.json

The following part describes the optional dynamic registration process of a client. Open CDE 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 /opencde/{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/opencde/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=="
}

2.3 User Services

2.3.1 Get current user

user_GET.json

Resource URL

GET /opencde/{version}/current-user

Example Request

GET /opencde/1.0/current-user

Example Response

Response Code: 200 - OK
Body:
{
    "id": "Architect@example.com",
    "name": "John Doe"
}