OK… so we covered what references were and how to add them in the last tutorial, References, References, References…
In this tutorial we will acquaint ourselves with the Revit API & SDK, where to find it and how to read it…if you have previous programming experience you will probably feel at home with the API help document, but if you don’t it is quite daunting getting started. I’ll try to explain it as simply as I can, but I won’t be able to cover it all…It’s a massive document, but once you get the hang of reading the help file it will open up some huge metaphorical doors to Revit and what you can make it do.
Where does one find the API…and what is it anyway?!?
A lot of software have an API (Application Programming Interface), this allows us mortals to mess with the code the programming gods generously gifted to us to make some cool things they didn’t think of, or wasn’t worthy of their godly skills and sometimes for us just to mess with the software and get it to do silly things that probably shouldn’t be done…ever.
The Revit API is pretty generous, it allows you do pretty much most things but not everything. There will be instances where what you want to do is simply just not possible…but these times are rare but frustrating.
First of all, we need to download what is called the Revit SDK (Software Development Kit). Be careful though, the Revit API/SDK is version specific. The API changes between versions of Revit and even updates (especially major ones like the R2 updates). You, being the developer, need to be mindful what changes have occurred between the API versions as the script you write may have been made obsolete in future versions or changed in later versions. Fortunately, this is well documented and I will show you where you can find this information later.
You will notice in the download link above, that it takes you to Autodesk’s Developer Network. Here you will find some tutorials on how to get started writing Add-ins, I would recommend having a look at these too, they are done in the C# programming language and Visual Studio. We will be sticking to Dynamo/Python, but I started with C#, sharpdevelop and VS and if you want to create a proper Add-in then do have a look as not all scripts should be done using Dynamo.
Once you have downloaded the SDK for your version or Revit you’ll see that you have a few things in there, we will be focusing on the RevitAPI.chm from here on…
This is the help file and has all the NameSpaces, Objects, Methods and Properties which you will need to make something awesome.
A helping hand…
Understanding the help file is critical to understanding the API since this file documents to whole API, but where do we start? Well, we’ll start by opening it and getting familiar with how it’s setup and I’ll make some comparisons to how the structure is similar in a way to how Revit is set up (this helped me understand how it all worked anyway)…
In the image above, this is what you will see upon opening the help file for the first time. Looks a little scary, but these are the contents by Namespace. I explained Namespaces in a previous tutorial and how they are similar to a book in a library, but if you are unsure what they are here is an explanation by dot net perls. Or just google, plenty of good explanations out there.
If you select the Autodesk.Revit.DB namespace from the contents list you will get a whole list of available classes to inspect, these are classes specific to the Revit Models DataBase (hence the DB Namespace). Classes are sort of like templates for creating objects with functions and properties – Members (Methods/Properties). This is a key concept in OOP (Object Oriented Programming). If we were to look at Revit as our guide to understanding OOP, imagine that a Namespace represented whether an element was a Model Element or an Annotation Element in the VG (these overarch their categories), classes in this case would be along the lines of the categories in each. Classes define the function of the Object so when you create an object then this is based on a class, just like when you create a Revit Element it is based on a Category. More about classes here. This makes a little more sense when we look at the Autodesk.Revit.DB.Element Class below. To get to this look at the image above and select “Autodesk.Revit.DB.Element” from the list of classes in the Autodesk.Revit.DB Namespace…
The above shows all the subclasses that Inherit from the Element Class, as mentioned earlier, Classes are like a template, the subclasses listed within the Element Class inherit their properties/behaviour from the Element Class – like parents pass on some of their charicteristicts to their children. As we compared classes to be like categories, you could think of subclasses like different types of Families within a category. They all have similar behaviours e.g. all structural framing families are line based and have similar functions although they may be concrete or steel etc.
Just like Revit Elements, classes have properties and specific functions, these are called Members. We will have a look at the Members of the Element Class – if you scroll right down to the bottom of the Element Class page, you’ll see the following…
If you select Element Members you will expose all the Members associated with the Element Class starting with it’s Methods…
Methods allow you to perform functions/operations on the Objects of this Class you are working with and are very handy and we will be using them quite a bit. If you scroll down further you will find the properties…
The Properties of the Element Class give you access to some information about that Element. This could be it’s Name or the ElementId or it’s Category. We will also be using these a lot as they are really useful. They are similar how Revit Elements have Properties, they hold information about that Object.
Once you get familiar with what the help file you can search for Classes, Methods and Properties using the Search Box, this saves heaps of time traversing the seemingly endless help file to get what you are after. You can find this in the tabs at the top of the pane on the left.
Alternatively, you can find the API documentation online here. This also has some Python code snippets too, check them out!
Anyway, that about covers the Intro To The Python Node. Let’s move on to some Worked Examples as this is where you will learn how to start putting down the lines of code and how this ties up with the API docs.
danimosite.wordpress.com 
Leave a Reply