Migrating API V1 to API V2

Introduction

This documentation will guide you through the process of transitioning from API V1 to the new API V2. It will also provide information about the migration plan and outline what you can expect in our new API version. Our primary goal is to assist you in achieving a smooth and successful transition to Holistics’s latest API version.

Why it is time to move to API V2

For the past few months, we have considered API V1 as our legacy API. While it is still functional, it is not actively maintained. Meanwhile, we have been developing API V2 as a more powerful, flexible, and well-structured version of V1.

Now that API V2 has surpassed its predecessor in both functionality and experience, we are deprecating V1 and are here to assist you in migrating your applications to V2.

Our deprecation plan for API V1

info

The entire API V1 will cease to function by November 20th, 2023.

This deprecation includes all functionalities available in these two V1 kits:

• Users API
• Group API

Be assured that we have supported all of these functionalities API in V2.

Next steps, you will need to manually update your applications that are utilizing V1 to switch them to V2.

Equivalent functions between API V1 & API V2

API V1	API V2	Changes
[User] Get all users in a tenant with full information	GET - List users	Groups are in a different list, not included in each user V2 applies pagination, you have to query page by page V2 has user counter information
[User] Invite a new user to Holistics	POST - Invite Multiple Users	V2 allows inviting multiple emails with additional user settings, including API usage, group IDs, and data export permissions
[User] Resend invitation to user	POST - Resend invitation to user	We introduced inviting multiple users API in API V2 In order to make invite multiple users and resend invitation user consistent, we return the job info of created job
[User] Soft-delete a user	DEL - Delete a user
[User] Restore a deleted user	POST - Restore a deleted user
[User] Allow/ Revoke a user's API access	PUT - Update user	By setting attribute: allow_authentication_token: boolean
[User] Revoke Authentication Token from a user	PUT - Update user (Upcoming)
[User] Check whether email address is already used for a user in Holistics	GET - Check whether an email address is already used for a user in your Holistics workspace
[User] Change user role in Holistics	PUT - Update user	By setting attribute: “role”: enum remove_groups: passing empty group_ids
[Group] Get all groups in a tenant	GET - List Groups	V2 applies pagination, you have to query page by page V2 includes all users’s id instead of num_user in V1 V2 supports include_users
[Group] Create a new group	POST - Create Group	Response’s structure change
[Group] Update information of an existing group	PUT - Update a Group	Now included user_ids in groups
[Group] Delete an existing group	DEL - Delete a Group
[Group] Add a user into a group	POST - Add User to Group
[Group] Remove a user from a group	POST - Remove User from Group

FAQ

How will the migration affect existing applications that are utilizing API V1?

• We expect no interference in your automation workflow after the migration since all functionalities of V1 are completely covered by V2
• However, since there will be some differences in the data schema (or response structure) between the two versions, you would need to follow our documents to set up precisely

Should I do anything prior to this migration?

We suggest you check which applications will be affected by such an update, and inform your team that they will not be available during that time.

What do I do if I encounter unexpected issues?

We are committed to providing support throughout the migration. If you encounter any problems, please reach out to us at [email protected] for assistance.