Tooling and Analytics APIs—What They Are and When to Use Them

The Tooling and Analytics APIs are new since my blog post Salesforce APIs – What They Are & When to Use Them. I sat down with Pat Patterson, Principal Developer Evangelist at Salesforce to learn more about these APIs.

A while back I wrote a blog post called Salesforce APIs – What They Are & When to Use Them. Since then, we’ve been hard at work here at Salesforce and there are some new APIs to tell you about.  So I sat down once again with Pat Patterson, Developer Evangelist Architect with Salesforce, to talk about these new additions to the integration tool box.

D: Pat, thanks for talking with me today. It’s been a while since we last talked about Salesforce APIs.

P: It has!

D: We’re here today to talk about two new APIs.

P: That’s right, since our last discussion we now have the Tooling API and the Analytics API.

D: Great. Let’s start with the Tooling API, what’s that all about?

Tooling API

P: The Tooling API is a REST API for manipulating code assets. Code assets include things like Apex classes, Visualforce pages, Apex triggers, and so on. This API is aimed at developers that want to build development tools for the Force.com platform.

D: Interesting. So what’s an example of a tool that someone might build using this API?

P: A great example of a tool that uses the Tooling API is MavensMate written by Mavens Consulting, who is one of our Salesforce partners. MavensMate is an open source, free tool that’s a Force.com IDE. It’s similar to the Salesforce Force.com IDE, but instead of using Eclipse, it uses the Sublime text editor. A lot of developers use and like Sublime because it’s a bit more lightweight that Eclipse and not tied to one particular language. So with the MavensMate Sublime plug-in you can do things like retrieve and save your Apex classes from within Sublime.

D: Interesting. I just recently had to install Sublime for a JavaScript class that I took. [Pat looks confused] A training class, that is, not a JavaScript class in code. [laughing]

P: A guy named Joe Ferraro at Mavens Consulting built MavensMate because he preferred using Sublime to Eclipse.

D: OK, so I’d like get a mental picture of what this actually means. Let’s say you’re in Sublime, you could create a Visualforce page and then save it right into Salesforce?

P: Right. You associate a directory on your computer with a Salesforce organization (org). Then when you create a project, you enter your Salesforce credentials and other information and you can access your Salesforce code assets from within your editor.

D: Very cool!

P: The Tooling API also opens up other interesting avenues. For example, let’s say you’re writing an app and you need to create a trigger dynamically at run time. Maybe that app requires a trigger on an sObject, you can using this API to add it. In addition to working with existing code assets, you can use the Tooling API to inject code into an org. It’s very powerful and has a lot of interesting applications.

D: So you can use it to dynamically generate any kind of code, like if you wanted to dynamically create a Visualforce page?

P: Right. When the Tooling API first came out, I created a code example that took an existing class and added a method to that class. The code added an interface, added a method and then called that method. In that code example the class operates on itself. So you can do some very powerful things with this API. It’s now possible to write self-modifying code.

D: Wow, futuristic. Is your code example publicly available?

P: Yup, it’s called Bodger and you can find it in my GitHub repo. The other cool thing you can do with the Tooling API is execute code. So you can use it to issue execute anonymous commands. You can also use it to run tests and retrieve Apex logs.

D: What objects can developers access by using the Tooling API?

P: Some of the most common objects that developers use this API to work with are Apex classes and triggers, Visualforce pages and components, and static resources. But the API supports many more entities. For a full list of what’s supported by this API, there’s some excellent documentation in this topic When to Use Tooling API which is pretty handy.

D: One question that comes to mind is how does this compare or how does this API fit in with the Salesforce Metadata API?

P: That’s a really good question. The Tooling API is for operations related to code, whereas the Metadata API is more for working with org metadata. Something like saving a set of Apex classes fits squarely within the Tooling API functionality. On the other hand, synchronizing the log in IP range on a user profile from one org to another falls directly within the Metadata API functionality. The boundary is a bit fuzzy, and in fact, is getting fuzzier, as we are adding workflow rules and validation rules to the Tooling API in the Summer ’14 release. You’ll see us expanding the Tooling API and making more and more use of it in our own tools as we implement our ‘API-first’ strategy.

D: I see.

P: So that’s a good way to think about it. If you want to write code to work with Salesforce code assets which could be anything from Apex classes and triggers to Visualforce pages to custom fields, you would use the Tooling API. If you want to write code to work with things like org settings, profiles, connected apps, and objects like that, you would use the Metadata API.

D: Great! Let’s move on and talk about the Analytics API. I’m guessing it’s related to reports?

Analytics API

P: That’s right. The Analytics API is a REST API designed to let you programmatically run reports and retrieve report data. It’s really cool because you can run reports synchronously or asynchronously. So you can code it such that your app waits for the response to come back; or if it’s a report that takes a bit longer to run, your app can call the report, maintain a reference to it and then continue processing.

D: So being able to programmatically run a report and get that data means that now you aren’t limited to viewing the data only in a static report?

P: Exactly. So that lets you do things like process report data to show it on a Web page, for example. You could also call the Analytics API from a Visualforce page. This API gives you a lot of flexibility because you can retrieve report data in JSON and then what you do with the data is up to you. You might want to present the data in a different UI or use it in an integration scenario. The sky’s the limit.

D: So this API returns the data only in JSON?

P: That’s right.

D: What’s an example of what you can use this API for?

P: Well, I wrote a blog post that shows an example of running the Opportunities by Type standard report using the Analytics API. The code runs the report, retrieves the data, and then displays it graphically in a nice pie chart using Google Charts.

D: That sounds like a great example.

P: The code example has a dropdown that lets the user select which column of data they want to show in the chart. So it’s a simple example, but it showcases a lot of the functionality of the API.

D: Nice. I can see where retrieving report data and working with it outside of a Salesforce report would really be helpful in integrating with Salesforce.

P: Another nice thing about the Analytics API is that it’s available via Apex as well. So in the same way we released the Chatter REST API and then we made that available via Apex, we did the same thing for the Analytics API. If you want to run reports from Apex code, you don’t need to jump through hoops making REST calls from Apex back into your own org to do that. It’s all available in the Analytics API via Apex.

D: So it’s built right into Apex. That’s great.

P: Right, there’s a reports namespace and a reports class that you just work with directly in code.

D: Anything else developers should know about the Analytics API?

P: There are specific limits for reports so you’ll want to be aware of those. You wouldn’t want to do something like use the Streaming API to get notifications on data changes and then run a report every time the data changes. You could run into limits if you use the APIs in that kind of a high-volume way. Just something to keep in mind.

D: Great advice. To wrap up, how can readers find out more about these APIs?

P: Check the Resources section below in this post. You’ll find links to documentation, code samples, blog posts, and videos. Lots of options for learning more.

D: Awesome. Thanks again for your time.

P: My pleasure!

Resources

Leave your comments...

Tooling and Analytics APIs—What They Are and When to Use Them