Contribute an API Integration

How to contribute an integration to Revert

1. Ensure that the project is configured in the local environment following the instructions outlined here. Establish a connection to an existing application and test various endpoints to verify proper functionality.

To establish the connection with one of the app,watch this video of ClickUp integration ClickUp Integration and follow the other steps in the “Test Your Integration” section below.

2. Analyze the authentication and authorization flow based on the requirements of the third-party API. Identify the appropriate authentication type, which may include options such as Basic, OAuth 2.0, OAuth 1.0, API Key, etc depending on the thirdparty.

3. Incorporate your third-party integration by adding it to the Prisma TP_ID enum.

4. Incorporate the designated value as a string (previously set in the TP_ID enum in the Prisma schema) within the suitable category in both packages/backend/common.ts and packages/backend/prisma/seed.ts.

5. Execute the command yarn workspace @revertdotdev/backend migration:dev to apply the necessary database migrations.Also run this to seed the new changes to db tables yarn workspace @revertdotdev/backend db-seed.

If you are making changes to prisma files and you want the data in the db tables for proper functionality of the feature you are working on, then always seed the db.

6. Implement the recommended authentication and refresh token flows for the third-party integration. To generate access tokens and establish a connection, refer to the relevant code in packages/backend/routes/v1/ within respective sub-packages like crm, chat, ticketing, etc. For the refresh token flow, inspect the methods available in packages/backend/services/auth.ts, for categorized token-refreshing methods such as refreshOAuthTokensForThirdParty and refreshOAuthTokensForThirdPartyTicketServices. If your integration doesn’t have a refresh token mechanism,study the absent integrations in the above files and proceed similarly.

If you are introducing a new category that lacks a corresponding structure in the project, feel free to create new packages as needed. Should you require assistance, please don’t hesitate to reach out to us on Discord.

7. Prior to Unification, when implementing any given endpoint, initiate the process by generating a fern configuration for it. Ensure that thirdparty endpoint/operations for the specified API are conducted through Revert.

8. For the given endpoint(s), unify the schema and fields by implementing them in packages/backend/prisma/fields.ts.Seed the db here again.

Unification Process. Performed while retrieving resources from third party to match the provided schema. The process involves the following steps:

  1. Request to Third-Party Endpoint: Begin by initiating a request to the third-party endpoint.
  2. unifyObject: After receiving the response, pass it to unifyObject, incorporating a preprocessing to standardize essential values.
  3. transformFieldMappingToModel: Send the preprocessed data to transformFieldMappingToModel, which aligns it with the provided schema.
  4. Unified Response: The processed data is returned as a unified response.

Disunification Process. Primarily performed during the creation or updating of a resource. When a create or update request is made, it is initially in the format defined by Revert. This format is then disunified to align with the structure accepted by the third party. The process involves the following steps:

  1. disunifyObject: The initial Revert-defined format is disunified.
  2. flattenObj: Extract additional values from the object.
  3. transformModelToFieldMapping: Convert fields to match the format accepted by the third party, which is the reverse of the transformFieldMappingToModel step in the unification process.
  4. postprocessDisUnifyObject: Modify values to align with the expectations of the third party.

9. Add changes for your integration in the functions involved during the Unification and Disunification process.

Test Your Integration

For testing your integration while integrating it with revert.

  • Go to packages/js folder and create a new file .env and copy the content of .env.example.

  • Run yarn dev:all

  • Go to packages\react\src\App.tsx and paste you public revert token from localhost:3000 in place of localPublicToken.

  • Go to localhost:3001 and start your testing.

Here’s a video showing final testing of an integration.It is a video testing the ClickUp integration.

ClickUp Integration