v1 to v2 Scope Oversight

API
, ,
1

Hello,

It appears that there is a rather major oversight in the v1 → v2 conversion which the team seriously needs to address, given the deprecation date is fast approaching.

As part of the migration from API v1 to v2, “related data” objects were removed from relevant APIs. Quoting from the migration docs:

Related objects have been removed from API responses to prevent too eager fetching of unnecessary data. Use subsequent API calls to fetch them if you still need them.

For example, this is the effect of this on the deals API (also quoting from the migration docs):

creator_user_id, user_id, person_id and org_idfields no longer contain an object but the relevant id.

I think this is a really terrible design decision, as now getting simple information that the deals API used to return (such as Person name + email, Owner name + email, and Org name + address) requires making 3 extra API calls, which defeats the purpose of reducing token usage, slows down integration, and increases complexity.

However, the real issue is that each of these relevant APIs (Persons, Organizations, Users) is in a different scope than the deals API. Previously, you could retrieve all of the aforementioned simple information about a deal simply by having read-only access to the Deals scope. Now, getting this information requires additional scope.

What this means for existing apps is that in order for their functionality to not break come January 1, they need to request additional scopes that they otherwise wouldn’t need. And users have to accept the additional scopes, alongside all the extra potential data leakage, in order to continue using the app.

I’m asking the team to seriously reconsider reintroducing basic related information into the Deals API, and doing the same for other, similar APIs. There already is an include_fields paramater that could be used, or a new parameter could be added. Alternatively, they could even add new APIs to retrieve related object data. Similar APIs exist for deal products and participants, and used to exist for persons before being deprecated.

1 Like