Updates on our RESTful APIs

Hi Austin! Good questions. I'll try to clarify here. Classic disclaimer applies here - this is all still under investigation and references beta features that are not yet committed to production. Finally, we acknowledge the road ahead on making sure these messages are clear and I'm working closely with @Adam Hoover to make that happen. You just happen to be a few weeks ahead of us with your questions - which is not a bad thing!

First, we intend to offer "Parity+" for the high value and most commonly used APIs. What that means is that we have to be diligent about what we bring over and what we don't. Let's start with things we may not migrate. An example is API_GetRecordInfo. We don't intend on offering a comparable API for that. It is more streamlined, simple and easily understandable to simply hit our new records endpoint and filter to the record you want.

Another example might be API_GenResultsTable (delivering HTML) or API_GetRecordasHTML. Through research and usage patterns, we know that most use cases where builders want to pull record info into a custom script involves their own styling. It doesn't mean that there aren't cases where someone is happy to take our default HTML, though. When you combine that with our UI refresh and the increased customization builders desire, it makes it difficult to support a dedicated endpoint to get HTML, which may not even fully represent what that builder is looking for.

One that is more interesting, and we are still gathering info on is API_CopyMasterDetail. Much more advanced workflows are possible in Pipelines. So that is what we mean when we talk about being diligent, and ensuring that our investments are going into areas that provide a lot of value for the widest audience of people.

Now, when we look at the base operations - that starts with making sure we have a great experience for CRUD on records. The "+" in "Parity+" refers to the fact that our new reports endpoint allows you to do things like get the report schema and also run summary reports. These are things that weren't available in the XML APIs. Loosely, the plan is Records -> Schema -> Users/Groups/Roles.

That is some background. To answer your questions directly:

1. The comment about 60 endpoints to 10 endpoints is around the fact that a single endpoint, called Records, now handles the equivalent functionality of API_AddRecord, API_EditRecord, API_ImportFromCSV, API_DoQuery, API_GetRecordInfo, and most of API_GenResultsTable. It mostly also replaces API_GetNumRecords and API_DoQueryCount. If you count API_DeleteRecord and API_PurgeRecords, since those are also record operations, we have simplified a lot of functionality. That means less friction for you to get up and running, reduced risk on our end maintaining multiple endpoints, and more deep investment in specific areas. The "60" to "10" was an estimate, and we also learned we needed to break a couple of things out that we initially thought might be able to be in one call. We get a lot of inquiries today around which API to use when. So much so, I even held a session at Empower a few years ago that compared API_GenResultsTable and API_DoQuery.
2. The existing XML APIs will be around for a long time (measured in years). It would not be fair for us to ask builders to dig up their scripts from years old and replace everything when hundreds of millions of requests hit the XML API every month. That being said, we hope to provide enough value and incentives that folks are interested in converting to the RESTful APIs.
3. Finally, with regard to an SDK - I'd love to hear your input. We are still researching this one. I think there is a decent chance we do something along the lines of publishing an OpenAPI spec (no promises yet). To be transparent, the feedback around an SDK has been almost 50/50 on "nope, don't need an SDK" vs "of course I need an SDK". What are you looking to achieve out of one? Is it just easy implementation into a toolkit, or were you hoping we maintained some decorations and enhancements?

Hope this helps. Keep the questions coming.
​

------------------------------
Harrison Hersch
------------------------------