Upload API

Automate the process of uploading models

If you want to upload an IFC model to Bimshare from your application, you can use the Upload API. It consists of a number of methods, which are explained in more detail below.

First you request an upload URL with your API key. This upload URL will be valid for one hour. You can then upload your IFC file to the upload URL. After uploading, you can repeatedly query the model status until the result indicates the model has been processed. You can then use the embed and view URLs to view your model. Optionally, you can change the model name. There is also a method provided to delete your model.

Normally, after Bimshare processes a model, an e-mail will be sent to the user indicating that the processing succeeded. This e-mail includes a link to the model. This will not be done when you upload a model via the API, so that you can implement your own notification mechanism which is better suited to your application if desired.

Using the Upload API requires an API key. You can generate this API key on your account page. Keep this API key secret; anyone that knows it can use it to view your models, upload new models to your account and even delete models. It is possible to revoke this API key and change it into another value, in case you lose it.

The JavaScript Embed API does not require an API key. It communicates with an IFRAME that contains the Bimshare viewer. For the aforementioned security reasons, do not expose your API key to any end-user of your application.

Your client should implement the HTTP specification as in RFC 2616. For most popular languages and frameworks there exist libraries that handle this. You can send both HTTP/1.1 and HTTP/1.0 requests, although the former is preferred. In our API there are both GET and POST requests defined. GET requests are without side effects. POST requests might incur side effects. Requests are sometimes required to be URL encoded, refer to RFC 3986 for more details, specifically sections 3.4 and 2.1. Some requests answer with a JSON value. JSON is specified in RFC 4627.

Get upload model URL

http://www.mybimshare.com/api/get_upload_model_url

This method is used to obtain an upload URL that you can use to upload your IFC model to be rendered. The returned upload URL will be valid for one hour. The upload URL will be valid even if you change your API key in the meantime. There is no mechanism to revoke upload URLs, they automatically expire after one hour.

You can choose whether an e-mail should be sent to your account once processing is done. By default, this is not done for models uploaded via the upload API. This allows you to send a customized e-mail to your users easily.

We ask you not to generate URLs if you do not intend to use them for uploading a model, in order to reduce the load on our servers. It is fine to let URLs expire occasionally.

HTTP methods allowed: POST

The data that you should send should be of content type application/x-www-form-urlencoded. It should contain the following key-value pairs:

api_key	your API key
email	true if you want an e-mail to be sent once processing is complete, false otherwise (the default if you omit this parameter)

The result is of one the following.

405 Method Not Allowed	if the method used is not POST.
403 Forbidden	if the submitted API key is not valid or your subscription does not allow for use of the Bimshare API.
200 Ok	if an upload URL has been generated.

You can find the generated upload URL in the Location header of the response, provided the request succeeded.

Example request

POST /api/get_upload_model_url HTTP/1.1
User-Agent: curl/7.21.3 (i686-pc-linux-gnu) libcurl/7.21.3 OpenSSL/0.9.8o zlib/1.2.3.4 libidn/1.18
Host: www.mybimshare.com
Accept: */*
Content-Length: 72
Content-Type: application/x-www-form-urlencoded

api_key=a0a2d8e0d063bbb4309a4bfeddd5b584c30aaa3209afce47becfd23cf11ecac3

Example response

HTTP/1.1 200 OK
Server: nginx/0.7.67
Date: Fri, 16 Sep 2011 11:44:16 GMT
Content-Type: text/plain; charset=utf-8
Connection: keep-alive
Location: http://www.mybimshare.com/api/upload_model/99b371c87bfa29866fe3f55c6ce3a84aebbe05d322e030c10d6c9f45eb5a17e3
Content-Length: 0
X-Handled-By: 192.168.176.148:8000

Uploading the model

You can use the URL retrieved from the previous method to post the model data (an IFC file). An upload URL can be used at most once. If you want to upload more than one model, you will need to generated more upload URLs using the previous method. The upload URL is case sensitive.

HTTP methods allowed: POST

The data that you send must not be encoded. It must be an IFC file. The result is one of the following.

405 Method Not Allowed	if the method used is not POST.
403 Forbidden	if the upload URL has expired or the upload URL has already been used.
404 Not Found	if this URL cannot be found (it is not a valid upload URL)
200 Ok	if the model has been uploaded successfully.

The URL to query the model status can be found in the Location header of the response, provided the request succeeded.

Example request

POST /api/upload_model/99b371c87bfa29866fe3f55c6ce3a84aebbe05d322e030c10d6c9f45eb5a17e3 HTTP/1.1
User-Agent: curl/7.21.3 (i686-pc-linux-gnu) libcurl/7.21.3 OpenSSL/0.9.8o zlib/1.2.3.4 libidn/1.18
Host: www.mybimshare.com
Accept: */*
Content-Length: 22421232
Content-Type: text/plain

ISO-10303-21;
HEADER;
... and so on

Example response

HTTP/1.1 200 OK
Server: nginx/0.7.67
Date: Fri, 16 Sep 2011 11:52:27 GMT
Content-Type: text/plain; charset=utf-8
Connection: keep-alive
Location: http://www.mybimshare.com/api/model_status/3424c612757060f401155b22030f81c2857ec59a96a9510c39b6b81845f744bf
Content-Length: 0
X-Handled-By: 192.168.176.148:8000

Querying the model rendering status

You can use the URL retrieved from the upload URL to query the status of the rendering of the uploaded model. You can use this status URL repeatedly. You should use this method at most once every 10 seconds per model to avoid overloading the server with unnecessary requests.

HTTP methods allowed: GET

In your query string, include the API key under the key “api_key”. The result is one of the following:

405 Method Not Allowed

if the method used is not GET.

403 Forbidden

if your account does not allow for Bimshare API usage.

404 Not Found

if this URL cannot be found (it is not a valid model status URL)

503 Service Not Available

if the server detected that this URL was retrieved too often. You can try again in 10 seconds.

200 Ok

if the status query was successful. The content of the response is a JSON object. It has the following keys.

processed	a boolean that indicates whether the model has been rendered and is ready to be viewed.
failed	a boolean that indicates whether processing the model has failed.
view_url	if processed and not failed, contains a URL that points to the viewer for this model. if not processed or failed, is null.
thumb_url	if processed and not failed, contains a URL that points to the thumbnail for this model. if not processed or failed, is null.
model_id	if processed and not failed, an identifier that can be used in the JavaScript API to embed the viewer in your application. if processed or failed, is null.
name	The name of the model
modify_url	The URL you can use to modify the name of the model.
delete_url	The URL you can use to delete the model.

Example request

GET /api/model_status/3424c612757060f401155b22030f81c2857ec59a96a9510c39b6b81845f744bf?api_key=a0a2d8e0d063bbb4309a4bfeddd5b584c30aaa3209afce47becfd23cf11ecac3 HTTP/1.1
User-Agent: curl/7.21.3 (i686-pc-linux-gnu) libcurl/7.21.3 OpenSSL/0.9.8o zlib/1.2.3.4 libidn/1.18
Host: www.mybimshare.com
Accept: */*

Example response

HTTP/1.1 200 OK
Server: nginx/0.7.67
Date: Fri, 16 Sep 2011 11:56:28 GMT
Content-Type: application/json
Connection: close
Vary: Accept-Encoding
Cache-Control: max-age=30
X-Handled-By: 192.168.176.148:8000

{"model_id":null,"name":"api_upload_99b371c87bfa29866fe3f55c6ce3a84aebbe05d322e030c10d6c9f45eb5a17e3.ifc",
"view_url":null,"failed":false,"processed":false,
"modify_url":"http:\/\/www.mybimshare.com\/api\/model_modify\/3424c612757060f401155b22030f81c2857ec59a96a9510c39b6b81845f744bf",
"delete_url":"http:\/\/www.mybimshare.com\/api\/model_delete\/3424c612757060f401155b22030f81c2857ec59a96a9510c39b6b81845f744bf"}

Example response 2

HTTP/1.1 200 OK
Server: nginx/0.7.67
Date: Fri, 16 Sep 2011 12:24:41 GMT
Content-Type: application/json
Connection: close
Vary: Accept-Encoding
Cache-Control: max-age=30
X-Handled-By: 192.168.176.143:8000

{"model_id":"3424c612757060f401155b22030f81c2857ec59a96a9510c39b6b81845f744bf",
"name":"api_upload_99b371c87bfa29866fe3f55c6ce3a84aebbe05d322e030c10d6c9f45eb5a17e3.ifc",
"view_url":"http:\/\/www.mybimshare.com\/view_model\/3424c612757060f401155b22030f81c2857ec59a96a9510c39b6b81845f744bf",
"failed":false,"processed":true,
"modify_url":"http:\/\/www.mybimshare.com\/api\/model_modify\/3424c612757060f401155b22030f81c2857ec59a96a9510c39b6b81845f744bf",
"delete_url":"http:\/\/www.mybimshare.com\/api\/model_delete\/3424c612757060f401155b22030f81c2857ec59a96a9510c39b6b81845f744bf"}

Retrieving the list of models

http://www.mybimshare.com/api/get_model_list

The following procedure returns the list of all models that are uploaded to your account. Models that are currently being processed are also included in this list. The status of the model as well as information to access the model is contained in the list that is returned.

HTTP methods allowed: GET

In your query string, include the API key using the key "api_key". The result is one of the following:

405 Method Not Allowed

if the method used is not GET.

403 Forbidden

if your account does not allow for Bimshare API usage.

200 Ok

if the status query was successful. The content of the response is a list of JSON objects. The objects have the following keys.

processed	a boolean that indicates whether the model has been rendered and is ready to be viewed.
failed	a boolean that indicates whether processing the model has failed.
view_url	if processed and not failed, contains a URL that points to the viewer for this model. if not processed or failed, is null.
model_id	if processed and not failed, an identifier that can be used in the JavaScript API to embed the viewer in your application. if processed or failed, is null.
image_url	if processed and not failed, a URL to the image of this model (2000 by 2000 pixels) in PNG format; if processed or failed, is null.
thumb_url	if processed and not failed, a URL to the thumbnail of this model (640 by 480 pixels) in PNG format; if processed or failed, is null.
date_created	The date that the model was uploaded.
name	The name of the model
modify_url	The URL you can use to modify the name of the model.
delete_url	The URL you can use to delete the model.

Example request

GET /api/get_model_list?api_key=a0a2d8e0d063bbb4309a4bfeddd5b584c30aaa3209afce47becfd23cf11ecac3 HTTP/1.1
User-Agent: curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8r zlib/1.2.5
Host: www.mybimshare.com
Accept: */*

Example response

HTTP/1.1 200 OK
Server: nginx/0.7.67
Date: Fri, 27 Apr 2012 10:25:03 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Vary: Accept-Encoding,Accept-Language,Cookie
Content-Language: en-us
Cache-Control: max-age=30
X-Handled-By: 192.168.176.149:8000

[{"model_id":"3424c612757060f401155b22030f81c2857ec59a96a9510c39b6b81845f744bf",
"name":"api_upload_99b371c87bfa29866fe3f55c6ce3a84aebbe05d322e030c10d6c9f45eb5a17e3.ifc",
"view_url":"http:\/\/www.mybimshare.com\/view_model\/3424c612757060f401155b22030f81c2857ec59a96a9510c39b6b81845f744bf",
"failed":false,"processed":true,
"modify_url":"http:\/\/www.mybimshare.com\/api\/model_modify\/3424c612757060f401155b22030f81c2857ec59a96a9510c39b6b81845f744bf",
"delete_url":"http:\/\/www.mybimshare.com\/api\/model_delete\/3424c612757060f401155b22030f81c2857ec59a96a9510c39b6b81845f744bf",
"thumb_url":"http:\/\/www.mybimshare.com\/bsq\/storage\/3424c612757060f401155b22030f81c2857ec59a96a9510c39b6b81845f744bf\/thumb.png"}]

Changing the model name

You can use the URL retrieved from the status request to change the model name. This name is displayed to the user in the viewer. We recommend you to change it, since by default the name is a long string that is user-unfriendly.

HTTP methods allowed: POST

The data that you should send should be of content type application/x-www-form-urlencoded and should contain two key-value-pairs. One pair should have key 'api_key' and value your API key. The other pair should have key 'name' and as value the model name you want to set. The model name should be at most 255 characters long.

The result is of one the following.

405 Method Not Allowed	if the method used is not POST.
400 Bad Request	If the parameter 'name' could not be located in your request, or it was longer than 255 characters.
403 Forbidden	if your account does not allow for Bimshare API usage.
404 Not Found	if this URL cannot be found (it is not a valid model modify URL)
200 Ok	if the modify command was successful.

Example request

POST /api/model_modify/3424c612757060f401155b22030f81c2857ec59a96a9510c39b6b81845f744bf HTTP/1.1
User-Agent: curl/7.21.3 (i686-pc-linux-gnu) libcurl/7.21.3 OpenSSL/0.9.8o zlib/1.2.3.4 libidn/1.18
Host: www.mybimshare.com
Accept: */*
Content-Length: 87
Content-Type: application/x-www-form-urlencoded

api_key=a0a2d8e0d063bbb4309a4bfeddd5b584c30aaa3209afce47becfd23cf11ecac3&name=modelname

Example response

HTTP/1.1 200 OK
Server: nginx/0.7.67
Date: Fri, 16 Sep 2011 12:33:44 GMT
Content-Type: text/html; charset=utf-8
Connection: keep-alive
Content-Length: 0
X-Handled-By: 192.168.176.147:8000

Deleting the model

You can use the URL retrieved from the status request to delete the model. Deleted models are no longer accessible and do not count towards any quota that your subscription to Bimshare might have. You cannot undelete deleted models; deletion is permanent and immediate.

HTTP methods allowed: POST

The data that you should send should be of content type application/x-www-form-urlencoded and should contain one key-value-pair. The pair should have key 'api_key' and value your API key.

The result is of one the following.

405 Method Not Allowed	if the method used is not POST.
403 Forbidden	if your account does not allow for Bimshare API usage.
404 Not Found	if this URL cannot be found (it is not a valid model modify URL)
200 Ok	if the delete command was successful.

Example request

POST /api/model_delete/3424c612757060f401155b22030f81c2857ec59a96a9510c39b6b81845f744bf HTTP/1.1
User-Agent: curl/7.21.3 (i686-pc-linux-gnu) libcurl/7.21.3 OpenSSL/0.9.8o zlib/1.2.3.4 libidn/1.18
Host: www.mybimshare.com
Accept: */*
Content-Length: 72
Content-Type: application/x-www-form-urlencoded

api_key=a0a2d8e0d063bbb4309a4bfeddd5b584c30aaa3209afce47becfd23cf11ecac3

Example response

HTTP/1.1 200 OK
Server: nginx/0.7.67
Date: Fri, 16 Sep 2011 12:40:09 GMT
Content-Type: text/html; charset=utf-8
Connection: keep-alive
Content-Length: 0
X-Handled-By: 192.168.176.149:8000

Querying the model's list of views

You can use the URL retrieved from the upload URL to query the list of user defined views that are created by the user.

HTTP methods allowed: GET

In your query string, include the API key under the key “api_key”. The result is one of the following:

405 Method Not Allowed

if the method used is not GET.

403 Forbidden

if your account does not allow for Bimshare API usage.

404 Not Found

if this URL cannot be found (it is not a valid model status URL)

503 Service Not Available

if the server detected that this URL was retrieved too often. You can try again in 10 seconds.

200 Ok

if the status query was successful. The content of the response is a list of JSON objects. They have the following keys.

id	a unique integer that identifies this view, this key is not provided for the ‘Home’ view
name	the name of the view
url	a url to navigate to this view in the Bimshare Viewer.
thumb_url	a url to the thumbnail of this view in the PNG image format

Example request

GET /api/model_views/3424c612757060f401155b22030f81c2857ec59a96a9510c39b6b81845f744bf?api_key=a0a2d8e0d063bbb4309a4bfeddd5b584c30aaa3209afce47becfd23cf11ecac3 HTTP/1.1
User-Agent: curl/7.21.3 (i686-pc-linux-gnu) libcurl/7.21.3 OpenSSL/0.9.8o zlib/1.2.3.4 libidn/1.18
Host: www.mybimshare.com
Accept: */*

Example response

HTTP/1.1 200 OK
Server: nginx/0.7.67
Date: Fri, 16 Sep 2011 11:56:28 GMT
Content-Type: application/json
Connection: close
Vary: Accept-Encoding
Cache-Control: max-age=30
X-Handled-By: 192.168.176.148:8000

[{"url":"http:\/\/www.mybimshare.com\/view_model\/3424c612757060f401155b22030f81c2857ec59a96a9510c39b6b81845f744bf",
"thumb_url":"http:\/\/www.mybimshare.com\/bsq\/storage\/3424c612757060f401155b22030f81c2857ec59a96a9510c39b6b81845f744bf\/thumb.png",
"name":"Home"},{"url":"http:\/\/www.mybimshare.com\/view_model\/3424c612757060f401155b22030f81c2857ec59a96a9510c39b6b81845f744bf#67",
"thumb_url":"http:\/\/www.mybimshare.com\/bsq\/storage\/3424c612757060f401155b22030f81c2857ec59a96a9510c39b6b81845f744bf\/thumb_view123.png",
"id":123,"name":"My View"}]