V2 Migration Guide
Last updated
Was this helpful?
Last updated
Was this helpful?
If you have previously used Pitchly's V2 API and would like to learn how to move to the V4 API, this guide can act as a cheatsheet to help you during that migration process, whether you're adding support for V4 or replacing your current V2 implementation with V4.
In V2, you generate a Client ID and Secret by registering a new key set. In V4, you will need to to get a Client ID and Secret, since we are rolling out our V4 API on a controlled basis temporarily.
Once you have a Client ID and Secret, the way you authenticate will depend on your desired flow:
If your app used the implicit OAuth flow in V2 (response_type=token
), this flow has been in favor of the authorization code flow. In V4, the authorization code flow can now be used regardless of whether you have a server backend or not. In the past, the implicit flow was the only option if your app did not have a server backend. .
Once you have an access token, it's now time to use it.
In V2, depending on whether you were accessing data in your own organization or opted to use the OAuth authorization code flow, you would pass either your Client Secret directly in the secretKey
parameter or your access token in the accessToken
parameter in the variables of your GraphQL request.
The location of the GraphQL endpoint has also changed in V4. It is now:
In V4, errors are also now delivered differently. Errors now take the following form:
In V2, you would normally receive a token-invalid
error whenever a token was no longer valid. In V4, you will now receive an UNAUTHENTICATED
error in extensions.code
of the error response whenever the current access token is invalid.
If you are using the OAuth authorization code flow, when you receive an UNAUTHENTICATED
error response, you have the option to refresh the user's access token by calling the "refresh_token" grant.
While the process of using our GraphQL API is very similar between V2 and V4 and many of the core objects remain the same, the structure of requests have changed significantly to reflect the new capabilities and data structures in V4. This is also due in part to accommodate for scale. The V4 API utilizes more of the advantages of GraphQL, such as nested objects instead of only providing IDs to objects, which then must be separately queried, like in V2. You are generally able to get more data for less effort in V4.
Below are common product terms and their associated changes between V2 and V4.
Organization
Organization
N/A
Workspaces
Databases
Tables
Data/Rows
Records
Columns
Fields
Content
Content
Saved Filters
Views
User
Person
N/A
Team
App
App
App
Plugin
Integrations
Integrations
Integrations
Automations
In V4, you now pass all access tokens as a Bearer token in the Authorization header of every request, as shown below. .
The process of refreshing access tokens is nearly identical from V2 to V4. The only thing to note is that, if you downscope access tokens using the scope
parameter, the list of permissions you can pass have changed in V4. .
Here, we include only a few common requests to show how they have changed from V2 to V4. To see the full documentation of our V4 API, .
Note: The terminology has changed between V2 and V4. We now refer to Databases as Tables in V4. .
In V4, any property ending in "Connection" will return its data in a consistent pagination format. This format is a for pagination. Note that the pagination strategy has been changed from skip
/limit
to a cursor-based pagination strategy that now uses first
/after
. first
functions similarly to limit
. after
should generally be the last cursor
of the previous result. will return results that come after the after
cursor you specify.
Note that not all options for recordsConnection are shown here. to see all parameter options.
In V2, the content for all templates were previously returned. In V4, you must specify the template. This change was made to increase the performance of results returned. If you wish to get the content for all templates still, you can iterate over all of the and get their associated content.
Notably, content is now returned as part of record data instead of being a standalone endpoint that replicated a lot of the functionality of records. This means you can now more easily get record data and content together in the same record object without making multiple requests, if you choose, and you can use all of the same parameters offered by .
If you have any questions about migrating from V2 to V4, please don't hesitate to . We are happy to help in any way we can, and we are with you every step of the way.