API

Selected functionality of BriefBuilder is exposed in the form of an API (application programming interface), which selected partners can use to exchange BriefBuilder model data. An API can be useful for linking BriefBuilder to CDE’s (common data environments), parametric design applications, and for dedicated add-ins (such as the BriefBuilder Revit add-in).

See below for some info about the existing BriefBuilder API.

Documentation

The RESTful API is documented using Swagger and can be accessed here. Please note that you need a valid BriefBuilder user account to access the API documentation. If you do not have a user account, but would like to access the API documentation anyway, please contact us.

The API is designed to follow general REST principals. The following general error codes can be expected:
– 401 You are not authenticated.
– 403 You are not authorised for this resource.
– 404 Incorrect API url.
– 400 Incorrect API usage. Response contains a message regarding the nature of the error.
– 5XX BriefBuilder server error. Should generally not happen and indicates fault in the API implementation. Technical staff will be alerted automatically when this happens.

We expect API consumers to act as a TolerantReader. These API operations will be expanded over time and you should be able to handle additional fields that are not yet documented as well as missing fields that are documented as much as possible.

Access control

Access to our API is granted to authenticated end users, using the Swagger API documentation. Actual API access for third-parties is granted through our OAuth2 authentication protocol. Using this protocol, third-parties can request access the BriefBuilder data for a specific end-user, who has explicitly granted access for this by authenticating themselves on the BriefBuilder website. We are restricting the available OAuth2 grant types to Authorization code using Bearer tokens at this point in time for use cases where a third-party application provides additional functionality to all BriefBuilder customers. This will require third-parties to exchange the access code for an access token using their client secret credentials in a back-end application.

For direct one-to-one API access from a customer to their own data in BriefBuilder, we provide to option to use the Oauth2 Password grant type.

If you would like to receive a set of client-credentials for creating a third-party application integration, or programmatic access to your own BriefBuilder data, please contact us so we can discuss the possibilities.

Authorization code example

Once you have received a set of client credentials from us you can use them in the following manner. This example uses cURL to show the HTTP interactions and may be implemented in any language.

The first step is to redirect your end user’s browser to the following URL. This will bring up the BriefBuilder authentication page if the user is not authenticated yet, or if they already are they will be redirected back to your REDIRECT_URI.

https://api-app.briefbuilder.com/oauth/authorize?grant_type=authorization_code&response_type=code&client_id=CLIENT_ID&state=STATE_TOKEN&redirect_uri=REDIRECT_URI

Where the STATE_TOKEN can be any string from your side to later on match requests and ensure the belong to this initial request. The REDIRECT_URI should match (one of the) redirect URI’s you supplied to us when requesting a client id and secret.

When the authenticated user is sent back to your REDIRECT_URI, it will contain the following additional query parameters:

?code=AUTHORIZATION_CODE&state=STATE_TOKEN

The AUTHORIZATION_CODE should be used in the next step when your backend application retrieves the final access code. The STATE_TOKEN matches the token sent in the initial request by the end user. Use the AUTHORIZATION_CODE as follows:

curl -X POST --location "https://api-app.briefbuilder.com/oauth/token" \
    -H "Accept: application/json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=REDIRECT_URI" \
    --basic --user CLIENT_ID:CLIENT_SECRET

If the AUTHORIZATION_CODE is valid and so our your own CLIENT_ID and CLIENT_SECRET, sent as in the Authentication HTTP header (base64 encoded) you will receive the access (and refresh) tokens:

{
  "access_token": "YOUR_ACCESS_TOKEN",
  "refresh_token": "YOUR_REFRESH_TOKEN",
  "token_type": "bearer",
  "expires_in": 3600, 
  "scope": "read"
}

The refresh token may be used to get a new access token if it has expired:

curl -X POST --location "https://api-app.briefbuilder.com/oauth/token" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "client_id=CLIENT_ID&grant_type=refresh_token&refresh_token=YOUR_REFRESH_TOKEN" \
    --basic --user CLIENT_ID:CLIENT_SECRET

To use the access_token to access the API (token can be used until it expires):

curl -v -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H "Accept: application/json" \
https://api-app.briefbuilder.com/ext/api/project/PROJECT_ID/export

Password Grant example

Once you have received a set of client credentials from us you can use them in the following manner. This example uses cURL to show the HTTP interactions and may be implemented in any language.

Retrieve an OAuth2 access token using both your client credentials (CLIENT_ID, CLIENT_SECRET) and the you regular credentials, used to login to BriefBuilder (USERNAME, PASSWORD):

curl -v -X POST --user CLIENT_ID:CLIENT_SECRET \
https://api-app.briefbuilder.com/oauth/token \
-d 'grant_type=password&username=USERNAME&password=PASSWORD' \
-H "Accept: application/json"

If the credentials are all correct, the server will respond with a JSON response like this:

{
  "access_token": "YOUR_ACCESS_TOKEN",
  "token_type": "bearer",
  "expires_in": 3600, 
  "scope": "read"
}

Grab the value from the “access_token” field, in this case YOUR_ACCESS_TOKEN and use it in subsequent calls to our API in the Authorization header. For example, to retrieve a full requirements set for a specific project model, where PROJECT_ID is the id of the specific project:

curl -v -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H "Accept: application/json" \
https://api-app.briefbuilder.com/ext/api/project/PROJECT_ID/export