New to APIs or SDKs? This article explains the basic concepts you need before you start working with the BIMcollab API or the BIMcollab SDK. You don't need programming experience to follow it.
What is an API?
An API (Application Programming Interface) is a way for two applications to talk to each other.
Think of a restaurant. You don't go into the kitchen to cook your meal. You give your order to a waiter, and the waiter brings back your food. An API works like the waiter: your application sends a request, and BIMcollab sends back the data.
With the BIMcollab API, your own application can read and update data in a BIMcollab space, such as issues, projects, and documents, without a person clicking through the BIMcollab web app.
What is a REST API?
The BIMcollab API is a REST API. This means:
Your application communicates with BIMcollab over the internet, using the same protocol as web pages (HTTP).
Each type of data has its own web address, called an endpoint.
BIMcollab sends data back in JSON format, a structured text format that both people and applications can read.
Endpoints and base URLs
An endpoint is the web address for one specific type of data or action. Every endpoint starts with a base URL, followed by a path.
Example for the Connection API on the Playground space:
Part | Example |
Base URL |
|
Version |
|
Path |
|
Full endpoint |
|
This endpoint returns the list of projects you have access to.
Requests
A request is a message your application sends to an endpoint. A request contains:
A method: the action you want to perform (see the table below).
A URL: the endpoint you want to reach.
Headers: extra information, such as your access token.
A body (optional): the data you send, for example, the details of a new issue.
HTTP methods
Method | What it does | Example |
| Reads data | Get a list of projects |
| Creates new data | Create a new issue |
| Updates or replaces existing data | Update an issue |
| Deletes data | Delete a comment |
Responses
After every request, BIMcollab sends a response. A response contains:
A status code: a number that tells you if the request worked.
A body: the data you asked for, in JSON format.
Example response body for a list of projects:
[
{
"project_id": "64736bed-2fdc-4d9f-a35e-91568623e71b",
"name": "Example Project"
}
]
Common status codes
Code | Meaning | What to do |
| OK. The request worked. | Nothing. Read the response body. |
| Created. New data was added. | Nothing. |
| Bad request. Something in your request is wrong. | Check the URL, parameters and body. |
| Unauthorized. Your access token is missing or expired. | Get a new access token. |
| Forbidden. You don't have permission. | Check that your user account has access to this project. |
| Not found. The endpoint or item doesn't exist. | Check the URL and IDs. |
| Too many requests. You reached a rate limit. | Wait and try again. See Rate limits and handling HTTP 429. |
| Server error. Something went wrong on the server. | Try again later. If it keeps happening, contact support. |
Authentication and access tokens
BIMcollab data is private, so the API needs to know who is asking for it. Before you can send requests, your application must authenticate.
The BIMcollab API uses OAuth 2.0. In short:
A user signs in with their BIMcollab account.
Your application receives an access token.
Your application adds this token to the header of every request:
Authorization: Bearer <access-token>
The access token works like a hotel key card. It gives access for a limited time, and only to the data that the user who signed in is allowed to see.
📝 Note: For the full steps, see How to authenticate with BIMcollab API.
IDs and GUIDs
Most items in BIMcollab, such as spaces, projects, and issues, have a unique ID called a GUID.
A GUID looks like this: 64736bed-2fdc-4d9f-a35e-91568623e71b
Many endpoints need one or more IDs in the URL. You usually get these IDs from the response of an earlier request. For example, you first get the list of projects, then use a project ID to get the issues of that project.
Pagination
Some endpoints can return a large number of items. To keep responses fast, these endpoints return the results in pages. In the Documents API, the following parameters are required:
limit: how many items to return. Example:limit=10.offset: how many items to skip. Example:offset=0for the first page,offset=10for the second page.
What is an SDK?
An SDK (Software Development Kit) is a package of ready-made code and tools that developers add to their own software. Instead of building a feature from scratch, you use the parts that the SDK provides.
Back to the restaurant example: with an API, you order each dish from the waiter. With an SDK, you get a complete kitchen module that you install in your own building. It already contains everything it needs. You only connect it to your water and power.
Glossary
Term | Meaning |
Access token | A temporary key that gives your application access to BIMcollab data through the API. |
AppInterface | The code that connects the BIMcollab SDK user control to your application. |
Base URL | The first part of every endpoint address. |
BCF | BIM Collaboration Format, an open standard for exchanging issues between BIM applications. |
Callback URL | The address that BIMcollab sends the user back to after signing in. Also called redirect URI. |
Client ID and client secret | The credentials that identify your application when it uses the API. |
Endpoint | The web address for one type of data or action. |
JSON | A text format for structured data. |
Library | A collection of ready-made code that other software can use. |
Playground | The BIMcollab development space for testing integrations. |
Refresh token | A token that your application uses to get a new access token without asking the user to sign in again. |
Scope | The parts of the API your application asks permission for. |
SDK | Software Development Kit: a package of ready-made code and tools for developers. |
User control | A ready-made interface element that you place in a window of your application. |