If you are a developer who has been frustrated by HubSpot’s APIs, there are two things you need to know. First, you are not alone. Based on surveys and feedback, our APIs have been a significant pain point for our developer community, and we’ve received quite a few comments like these:
“The @HubSpot API was designed for marketers to make developers miserable.”
“We <3 you @Hubspot. But… you need a new API.”
Ouch.
The second thing you need to know is that our team has taken this feedback very seriously. After months of working on a solution, we are thrilled to announce that we are building the next generation of HubSpot’s APIs to provide a more seamless development experience.
By improving consistency across all endpoints and adding additional functionality, our next generation “v3 APIs” are designed from the ground up to ensure you spend less time troubleshooting and more time building innovative apps and integrations. Our first API to be updated, the CRM API v3, was released into general availability on March 31st, and more will follow in the coming weeks.
How did we get here?
Not too long ago, HubSpot was a startup. One of the great things about being a startup is how quickly small teams can iterate and experiment. But over time we began to scale, and more development teams were added to the mix with their own way of doing things.
Today we have seven different API teams responsible for overseeing nearly 500 endpoints, associated documentation, and billions of monthly API calls. In the past, these teams worked largely autonomously, and while that was great for moving at a rapid pace, it resulted in very inconsistent APIs.
As you can see in the example below, our existing endpoints have different naming conventions, versions, and structures. But what you can’t see in this image is that the problems run much deeper, impacting request and response models, query parameters, and interaction patterns, among other things.
Because each API is slightly different, there has been a steep learning curve and a lot of friction for anyone developing integrations with our platform. Just like our product has a consistent UI on the front-end across different objects and tools, our next generation v3 APIs are being redesigned to introduce uniformity across all endpoints on the back-end.
How are v3 APIs different?
Before we started developing our next generation APIs, we researched the most significant pain points for our developer community, and the patterns we identified have guided our efforts. In addition to systematizing naming conventions, versions, and structures, we’re also standardizing other important aspects of our APIs, such as:
- Paging
- Batch operations
- Archival/restoration
- Drafts and revisions for CMS assets
- Property and association interactions for the CRM
While the details of these updates go beyond the scope of this high-level overview, here are a few quick examples of the changes we’re making to paging and batch operations.
Updates to paging
We’re introducing consistent cursor-based paging for all of our collection endpoints. Check out this code sample:
$ curl "https://api.hubapi.com/crm/v3/objects/contacts?hapikey=demo"
{
"results": [
// contacts go here
],
"paging": {
"next": {
"after": "9437325",
"link": "https://api.hubapi.com/crm/v3/objects/contacts?after=9437325"
}
}
}
# Get the next page of results
$ curl "https://api.hubapi.com/crm/v3/objects/contacts?after=9437325&hapikey=demo"
Updates to batch operations
Batch operations are all being standardized so that moving from one endpoint to another feels intuitive. Check out this code sample:
$ curl --request POST
--url
"https://api.hubapi.com/crm/v3/objects/contacts/batch/create?hapikey={YOUR_HUBSPOT_API_KEY}"
--header “Content-Type: application/json”
--data ‘{
“inputs”: [{
“properties”: {
“firstname”: “Alice”,
...
}
}]
}’
How did we do it?
In addition to making our existing APIs more uniform, we have been working to build processes that will help our engineers avoid inconsistencies as they develop future APIs. Here are some of the tools we are relying on to ensure all of our development teams are on the same page:
- API Design Guide - To ensure all of our teams create consistent endpoints, we created high-level API design standards that document required practices.
- API reviews: We then completed detailed reviews of existing APIs and outlined what needed to be changed to make them consistent with the Design Guide.
- Automated API linter - We also created automated tooling that validates adherence to HubSpot’s API standards in real-time.
Other new resources for developers
Updated APIs aren’t the only thing we’ve been working on improving. Check out some of these other new developer resources that are designed to make it easier for you to build apps and integrations on HubSpot’s platform:
- Updated interactive developer docs
- API client libraries / SDKs
- Free Academy video course: an Introduction to HubSpot’s APIs
- Postman collections (available on each end-point doc page)
What’s next?
Here at HubSpot, we are on a mission to build a thriving platform with a host of third party apps and integrations, and our developer community plays a significant role in making this happen. That is why we take your feedback seriously and are excited when we can release improvements that will make your life easier as a developer.
So far, the feedback we have received during beta testing of the CRM API v3 has been a vast improvement. Here are a few of the comments we’ve seen via our developer forum:
“I just wanted to say I'm very very very happy with this new API, it simply solved half our ELT problems, thanks so much”
"I just wanted to say I'm generally loving the new API - thanks!”
"Very excited with the v3 API. The API seems more standardized.”
But we’d love to hear from you as well. So what’s next? Keep an eye on our Changelog to learn when we release new v3 APIs to developer preview or general availability. Then dive into our updated documentation to learn more about the details of each new API, give them a try, and let us know what you think.