Automating Autodesk® Revit® Server
Rod Howarth – Bornhorst + Ward
CP5022
The latest version of Revit Server offers a number of automation capabilities, from locking files and
creating directories to generating a new local file for a Revit central model. This class will explore these
options and consider some scenarios where they can be leveraged along with existing Microsoft®
Windows® and Revit APIs to perform time-saving tasks. A number of examples will be showcased,
including how to create a HTML replacement for the Silverlight® admin tool, how to create a Revit Server
folder from an existing system, and how it is possible to have a scheduled task that runs once a day,
creates a local file, opens it, and exports the model to a DWF™ without user interaction.
Learning Objectives
At the end of this class, you will be able to:

Explain how Revit server automation can be integrated into existing software processes

Describe the REST interface to Revit Server

Combine the Revit Server command line and the Revit API to perform a task in a Revit model on a
schedule

Use the supplied command line utilities to automate Revit Server
About the Speaker
Rod Howarth is a software developer for Bornhorst + Ward Consulting Engineers Pty. Ltd.
based in Brisbane, Australia. For the past few years, he has aided the company's transition
from AutoCAD® to Autodesk® Revit® Structure by making use of the Revit API. He has
created add-ins that have saved Bornhorst + Ward drafters many hours of work by automating
some of the more tedious tasks in Revit.
Contacting the Speaker
Email: mail@rodhowarth.com
Twitter: @rodh257
Web: http://rodhowarth.com
Automating Autodesk® Revit® Server
REST API Overview
What is the Revit Server API?
The Revit Server API allows you to administer the folders and models inside of your Revit
Server via code instead of using the online administration tool. All of the functionality that is
exposed in the Silverlight based administration tool is available through the web based REST
interface.
What is REST?
REST stands for Representational State Transfer, basically it is a way of creating a web based
API that uses URLs to interact with the server.
It is based on the HTTP Specification as outlined by the World Wide Web Consortium, and
forms the basis for all web servers, such as Apache and IIS. Your web browser will use REST to
communicate with these web servers to retrieve web pages and other resources.
The basic concept behind REST is that you are performing some sort of operations on a
‘resource’, generally your web browser will just be retrieving this resource, but you can also
make create, delete and modify resources.
What makes up a HTTP Request?
A resource is identified by a URL (which is why it is called a Uniform Resource Locator), this
forms part of the HTTP request, which has a number of parts:
Firstly, the HTTP Verb declares what action to take on the URL. These verbs include:



GET – This specifies that you want to retrieve a resource
POST – Sends an update to a resource to the server
PUT – Creates or overwrites a resource
2
Automating Autodesk® Revit® Server

DELETE – Removes the resource that is at the specified URL.
After indicating what action to take, the URL is specified. This forms a number of parts, which
you may be familiar with. Firstly, http:// specifies the protocol; this is unlikely to change for a
HTTP request (unless it is HTTPS for secure communication). Next is the server to contact to
retrieve the URL, this is usa.autodesk.com in our example.
Following this is where you are indicating the path to the resource on this server /company/ is
our example, but it could be just /, or /index.html, /banner.jpg or anything on the server. The
server will receive the request and use this portion of the URL to identify what exactly to return.
The first line of the request ends off with an identification of the HTTP version to use, which is
normally always HTTP/1.1
This first line could also include some querystring parameters, which are key/value pairs that
follow the resource. For instance:
http://server.com/resource?key=value&param2=value
would supply key, and param2 as parameters with their values. This is one way of giving the
server some extra information in your request. For instance, you could ask the server to rename
a resource, and use the querystring to state ?newName=name which may result in the server
renaming the object to ‘name’.
Aside from supplying parameters to the querystring, you can supply extra header values, which
are on the lines following the request line. These may be used to identify what browser version
you use, your username, or just supply other data.
What makes up a HTTP Response?
Once the server has received the request, it will perform its processing and return a HTTP
response. This is made up of a number of lines:
3
Automating Autodesk® Revit® Server
Firstly, the server returns the HTTP version and a response code. As you can see in the picture
above, the server returned a code of ‘200 OK’, which means the request was serviced correctly.
There are a vast amount of error codes, most of which you’ll never come across, but some
common ones include:
200 – Success
404 – Not Found (the resource was not found)
403 – Forbidden (you are not authorized to use that resource)
400 – Bad Request (you did not format the request correctly)
500 – Internal Server Error (something went wrong on the server)
You may come across them in your dealings with the Revit Server API. To read about other
status codes check out the W3 page on them:
http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
The status code of 200 means that we should get what we requested from the server, so we will
keep reading through the response.
The next line indicates what sort of content the response contains. In our example, the server
returns a HTML web page in UTF8 encoded text. However, the content type could be any MIME
type, such as:
text/html
text/xml
image/png
4
Automating Autodesk® Revit® Server
image/jpg
text/plain
You can read more about these here:
http://www.w3.org/TR/html4/types.html#h-6.7
After this is the header list, this is similar to the request headers, in that it adds extra information
to the response, such as the http server name/version.
Finally, we get to our data, in our instance, it’s the HTML text, but if it was a JPEG or a Revit file,
it would be binary data that we would need to read this correctly in our code, luckily .NET and
other frameworks have ways of converting binary to images or other file formats.
REST APIs
By now you’ll hopefully be able to see that browsers use HTTP to request/modify resources on
a web server, which returns the appropriate response, but how does this work as an API?
Instead of using a dll file that you include into your project just as you would when dealing with
the normal Revit API, REST API’s are language agnostic. This means that you can use them
from any language or framework that can make HTTP requests. This is handy for interfacing
with legacy code, in languages such as VB6/VBScript, which would otherwise not be able to
access it at all.
So instead of calling methods from a DLL, the URL and the HTTP Verb combine to act as a sort
of method call. You use the resource portion of the URL to identify the resource you want to
get/edit and you use the querystring and headers for extra parameters.
This gives the API’s a consistent and self describing interface which can be used from
anywhere that has an internet connection. As a result they are used by a large amount of web
companies, such as Twitter and Flickr for their API’s and there is a lot of information on the web
about them. You can read more about the REST here at Nettuts+ http://goo.gl/EHxmH or if you
are really keen, you can have a look at the RESTful Web Services book published by O’Reilly
http://goo.gl/NiuAh however it is probably only worth buying if you are interested in making your
own RESTful API.
When developing with REST API’s you’ll want to have some way of debugging them. The best
tool for this is Fiddler2 (http://www.fiddler2.com) which lets you view ALL HTTP requests that
are being sent on your system, including ones made from your code. You can then view their
full details, edit them, resend them and view their data. It’s a must have utility.
The Revit Server REST API
Now we’ve learnt about REST API’s, what about the Revit Server one in particular? The best
place to look for information on this is the Revit 2012 Software Development Kit, which has a
Revit Server SDK folder.
5
Automating Autodesk® Revit® Server
This folder has a PDF with all the documentation you need to use the REST API.
Once you have a Revit Server Instance installed, you will then be able to use the API through
this base URL:
http://servername/RevitServerAdminRESTService/AdminRESTService.svc
Where servername is the name of your server (or you could use localhost if you are running the
code on the actual server).
After this URL, you add the resource you want to modify and send your requests. You also need
to supply some headers to each request that identify yourself and your request.
There are 2 categories of functionality that make up the Revit Server API, they are:
Information Querying API’s
These are mainly GET requests, for things like server properties, folder contents, directory
information and model save history.
Data Managing API’s
These are PUT/POST/DELETE requests generally, and they involve locking and unlocking
models/folders as well as creating, deleting, moving and renaming folders/models.
You should refer to the guide for the format of each request, but here are two examples:
6
Automating Autodesk® Revit® Server
GET /{folderPath}/contents
this request returns a JSON object listing the models and folders. If you don’t know what JSON
is, check this link out: http://goo.gl/R09r3
For example:
GET http://BASEURL/AUJob/contents
would return the contents of the AUJob folder under the main directory. A tip here is that if oyu
want to get the listing of everything in the main Revit Server Directory, use a space, as in:
GET http://baseurl/ /contents
Another example is
PUT /{objectPath}/lock
which locks the specified folder or model
for example
PUT http://baseurl/AUJob|subfolder|Model_01.rvt/lock
would lock Model_01.rvt, under the subfolder named ‘subfolder’ in AUJob.
Note that I used a | character to specify a subdirectory instead of a /, this is because /’s are
used in URLs.
Revit Server Command Line Utilities
In addition to the REST API there are two command line utilities that let you interact with the
Revit Server. These both come with the Revit Server installer, and are confusingly named very
similarly to each other.
RevitServerCommand
The first is RevitServerCommand which is available on the Revit Server itself, and simply allows
you to lock and unlock models or folders from a command line. This could come in handy if you
are writing batch files on the server and don’t want to muck around creating a web request.
7
Automating Autodesk® Revit® Server
RevitServerToolCommand
The next is RevitServerToolCommand (see, confusing). This comes both on the Revit Server
and with each Revit 2012 installation (situated under the Revit
Dir\Program\RevitServerToolCommand) this is crucial as what this tool lets you do is create a
local file from a model located on a Revit Server. So without opening Revit, you can download a
copy of the Revit model to your machine, all setup as a local file ready for use. In our
RevitRemoteBoot example, we make use of this utility, so check out the video to see one way
you might make use of it.
8
Automating Autodesk® Revit® Server
Revit Remote Boot
Revit Server stores every model on the central and local servers (as long as they have been
accessed on that server), meaning that across a number of servers you have the Revit file on
that machine, ready to be quickly opened. This opens up a number of potential uses.
Revit Remote Boot is an example of one of these uses. Put simply, it is a couple of interacting
programs that allow you to perform an operation on a Revit model from a script.
Take a look at the video for a full demonstration of what it does.
9
Automating Autodesk® Revit® Server
Basically your application can save an xml file in a certain directory, which ads a ‘job’ to the
queue. Then, using the RevitServerToolCommand, you can, from a batch file, create a local
copy of the Revit Model you want to work on, and open it in Revit. From there, a Revit API addin will detect that you’ve opened a model that corresponds to a job, and will run the other Revit
API add-in that was specified in the job file. After this is done, the job is marked complete, and
Revit is closed.
In my example, I’ve done a simple export to DWF of the model, the idea being you could set this
up to run at 1am every night, and export the DWF model to a certain location – perhaps for
viewing in Design Review on mobile devices. However, you could use it for any Revit API addin. For instance, you could have a high powered server which you setup as a local Revit Server
just purely to run this Revit Remote Boot. On this server you could create a job to run a
structural analysis add-in, or other computationally expensive stuff. This way you can setup your
own “cloud”, running Revit directly. You could also run certain audits on a model, for example,
you could create an add-in that counts the number of warnings present in the model and saves
this to a database, for displaying in a ‘hall of shame’ on your company intranet. 
This is highly experimental, and has some pitfalls, so should be considered as a proof of
concept, rather than a production ready program. The main pitfall is that any errors that come
up are shown as dialog boxes, and there is no easy way to deal with this in Revit. To get around
this I’ve used AutoHotKey (http://www.autohotkey.com/) to detect certain dialogs and close
them, but if there are unexpected ones, it will fall over.
10