Harry Mattison – Demystifying Revit API’s – TABLED SUMMARY ATTACHED

Q: Can you tell us a bit about your journey in getting involved with Revit API

My journey to the API was that I was the Quality Assurance Manager for Revit Architecture and Revit Structure for several years, starting when Revit was a small startup company with no customers and before our first release. I always tried to use scripting techniques with languages like Perl to improve our testing efficiency and completeness, and was excited when a member of our QA team was able to use the API to greatly expand the range of programmatic testing that could be done far beyond what could be tested if we were limited to manual interaction through the user interface.

 In 2008 I transferred to a software development position in the API group and have been helping design and test new API functionality (such as the Family Editor API and Conceptual Massing API in the 2010 release), teach other Autodesk employees about the API, work with the writers for the API documentation, design and write API samples, and more.

 ‘ I think an interesting future for this might be what www.guru.com has been doing to match freelance developers with potential customers. Not every Revit user will want to code their own Revit API applications, but having access to a worldwide network of developers interested in doing big and small projects might work well for both groups .’ – Harry Mattison    (May 2009)

Here is a great Revit API summary compiled by myself with the endless help and patience from Harry Mattison & Guy Robinson.

RTC 2009_ API Summary_M Louw


Understanding API potential – Interview with Guy Robinson

To be honest the journey into understanding API’s has been a challenging one for me and I clearly have so much more to learn in this foreign world of jargon and scripting logic. I do not even begin to suggest that I have any sense of possible outcomes that may arise as result of this journey but I do believe I have become a little clearer about our software add-on choices and their ramifications.

This enquiry has been about trying to understand the absolute basics of API’s and they could impact and potentially benefit us as users and managers of Revit. A spreadsheet and table follows that outlines some choices in regards to API’s and advice on when it might be appropriate for your firm to consider API’s.

I was lucky enough to interview Guy Robinson and ask him some questions about API, Revit and where he sees it all ending up….


Guy Robinson is an authorised Autodesk Developer who is based in New Zealand and works on a diverse range of international projects. I have been lucky enough to be able to get some of his time and advice on my quest to understanding what the Revit API is all about. Guy’s innate insight and candour has been helpful on my quest and I have jotted down some of his responses to my countless questions, in the hope that you may hopefully benefit from the insights and advice given by Guy Robinson himself.

NOTE: Guy Robinson is not informed about what changes Autodesk might be planning for the API in future releases and these comments are his opinion, to date, as things presently stand. As such the following comments reflect his current outlook and could be subject to change as new information comes to light or as Revit evolves as a product

Below is a transcript of that interview:

Q: How does a company evaluate when it is appropriate to create an API solution for a particular work flow outcome? What are the criteria’s for knowing when an API could be used? Do you have any suggestions?

A: This is difficult. I think the first test is – Can you do it manually in Revit? Although the API is incapable of replicating a lot of functionality, in many respects the Revit UI is a layer on top of the API. Be aware that if it’s not possible in the base application it won’t be possible via the API either. Make sure you understand how Revit works before customizing via the API.

If you want to do Group or Workset management via the API – forget it. There is no support for worksets or groups in the API. Well there is some group support…. but performance is appalling on large projects and it’s difficult to do updating efficiently. So if you use groups a lot then the API is not a great help. If you want to automate company standards throughout the firm then it is very limited support. See this post for more thoughts on this:

Q: What do you see as the biggest hurdle in regards to companies considering complex API’s or External Tool solutions for their business? How can this risk be minimized?

A: Software development is expensive. Plan thoroughly and be very clear on what you are trying to do short-term and long-term. Don’t compromise on BIM principles. Most architectural firms don’t have big budgets for R&D especially in the current economic climate. Plan carefully and make sure you are realistic about the API’s limitations and what the planned command will do for you. Also be aware that complex UI design takes time and money. Be prepared to stage rollout and projects in general. Sometimes getting the basic functionality working with a minimal UI as a first stage on a single project is a good approach. Then develop the UI further and roll out to the whole firm. This can minimise training costs as well as inevitably there will be bugs and modifications during development and in the early versions of a tool.

GUY: How do you see API solutions being used in Revit?

A: In broad terms a lot of API work in AutoCAD was about automating common documentation tasks within AutoCAD. In Revit and BIM/IPD the API shouldn’t be about this so much because that is what makes Revit unique in the first place. IMO, the API is as fundamental as drawing a wall with BIM applications because BIM is about managing data. For that reason company standards are critical, and which the API should play an important role. This is a moving target of course but Revit 2010 does offer a big step up with the new family API.

GUY: How do you see API solutions being useful to companies and who should be considering their use?

A: I firmly believe every Revit firm should be using the API just not via traditional methods necessarily. In the past I have consulted to firms trying to help them in achieving this. However it is my experience that with the exception of enthusiasts, most API work is currently done for large firms that can spread the cost over x number of employees. I just don’t think in it’s current form the API is economic for custom applications for anything except large firms or firms that will accept minimal UI’s or basic functionality. Also even via ADN it is impossible to plan long-term for firms as no information is posted on planned releases until they enter alpha or beta. So for some applications which have been large projects, they have not got past planning stage because firms haven’t been prepared to take this risk that some feature in the next release will break their application or become redundant in the next release. This is what I mean by the API being young. I have about 5 large applications that are sitting waiting for the functionality to be exposed via the API. For some applications it’s a waiting game.

Q: What benefits do you see API providing, other than external applications?

Applications can be spilt into 6 broad categories of applications in my experience:

1. Management : Includes management, correction and communication of Office standards and Building Regulations within a project.

2. Geometry Manipulation: Particularly useful for Structural and MEP disciplines in conjunction 3rd Party analysis solutions will use this extensively. Also may include for example calculations to modify family parameters based on the room the family is in and properties of the room such as room area.

3. Geometry Creation: Applicable to Revit 2010 in particular with the new Family API and mass tools. A powerful and well designed API will allow considerably easy and better management of families within projects and firm wide. Complex algorithm based form design is not possible before or requiring 3rd party tools such as SmartGeometry.

4. Geometry Translation: For converting Revit projects into formats not supported as standard. E.g. Game engines or STL. You’ll also see it being used as a gateway to 3rd party applications rather than exporting to a neutral format such as IFC.

5. Team communication: Helping coordinating of disciplines and teams in distributed projects. Via websites, IM or other web technologies.

6. Journals: Not strictly API but it remains the simplest method to automate functionality not supported by the current API..

Q: Can you tell us a little more about yourself and your vision or hopes of api-solutions in the future in regards to Revit?

A: Regarding visions, that is all in the hands of Autodesk and where they take Revit and the API. So I try and avoid visions on the API’s future ;-) A, I’m moving to developing applications to sell rather than custom development for now. Not the future I think is right for the API but for now the most appropriate given where the API is currently and likely to be in the immediate future A move to .NET3.5 with the R2010 API represents additional expense in development but also immense opportunity. Of course were someone to ask me to develop a large custom application for them then of course this would still be my preference.

Q: What you think is important for newbie’s know about using API’s?

A: …well… If you have no programming experience it’s a vertical wall to learning .NET and the Revit API. You will have some advantage if you a) understand the concepts Revit is designed around. b) have some programming experience. (Regardless of which language.) You need to understand the basic principles of object-oriented design.

Get a good book. And study over and over again the Revit SDK samples and documentation. The API documentation as of R2010 is VERY good. In addition be realistic and don’t expect the API to allow you to ‘fix’ what you see as perceived shortcomings in the existing Revit application. And failing that journal manipulation can be the simplest solution for many although it is fraught with maintenance and usability issues.

The API itself is only one aspect to software development you must consider. Resources and time will be spent considering issues such as:

1. Platform:  (Vista, XP, 64bit etc) which can be an issue if you want to communicate with existing older software which may not support 64bit.

2. UI design and complexity : This can add considerable cost to a project depending on how you wish to communicate with the user.

3. Project management : Do you need to roll out on a test server, do teams in different locations or

4. Deployment: Use a command manager or installer etc

Q: Where is the future of Revit api heading? What can you foresee that users might be able to do in a few years time through Revit external commands?

A: ??????????????????????????????? I’ll tell you when R2011 and then R2012 and then R2013… releases come out ;-) The current API is well designed but I guess each new release is restricted by what Autodesk want to release and the resources they have to achieve this.

Q: What is an example of one of the most useful API solution that you have seen or designed and what impact did it have on the business or project work-flow?

A: Well all my work is under NDA. Sometimes the simple projects make the users happiest. Complex spreadsheet integration is always a winner ;-)

Q: Do you offer API consulting services? How can potential clients contact your firm?

A: See contact details below. Feel free to email or call to discuss.


I would like to acknowledge Guy for all his patience, advice and encouragement. His feedback has been very useful in assisting me to share information in regards to Revit API that is relevant, accurate and responsible. In my communication with Guy it has been clear that he is always thinking of the best way to approach to solving a problem. He has also been quick to highlight any short-term and long-term pitfalls on any given solution. I can’t imagine that Guy could ever create any API solution that was not robust or really well-considered. Many Thanks.


Guy has his own blog [ http://www.redbolts.com/blog/] and is a .NET software Developer providing custom applications and commands for architecture firms exclusively working with Autodesk Revit and integration with any associated applications.