Unified API Request Flow

The Unified API Request is like a translator and assistant that simplifies how your application talks to multiple services (like Salesforce, HubSpot, or Zendesk). Instead of learning how each service works (different rules, formats, and endpoints), you just make one request to the Unified API, and it handles all the complicated stuff for you. In this section, let's go through each step of the Unified API Request.

---

1. Unified API Request
   • What Happens Here?
     The process starts when a user or application makes a request to the Unified API endpoint. For example:
     • Request: GET /unified/crm/accounts?search_term=Archith.

---

2. Is it a list,get call with static mapping?
   • What Does This Mean?
     Checks if the Unified API call is a list or get call. If it is, and Static Mapping is enabled, the API call isn't made and the Static Response configured is returned.

---

3. Are before steps configured?
   • What Does This Mean?
     Checks if there are any "before steps" configured for preprocessing the request. These steps are optional but can enhance or validate the request or fetch additional data which will be used in the Unified API call.

---

4. Run before steps (if configured)
   • What Happens Here?
     If before steps exist, they are executed.

---

5. Request Query Mapping
   • What Happens Here?
     Maps or converts query parameters to match the requirements of the API (e.g., Salesforce).
   • Example:
     • Unified API Query:

       {
         "name": "Truto",
         "city": "Bangalore"
       }

     • Mapped Query for Salesforce:
       SELECT * FROM Account WHERE Name LIKE '%Truto%' AND BillingCity LIKE '%Bangalore%'.

---

6. Request Body Mapping
   • What Happens Here?
     Adjusts or transforms the request body before sending it to the API.
   • Example:
     • Unified API Body:

       {
         "name": "Archith's Business",
         "website": "www.archithbiz.com"
       }

     • Salesforce Mapped Body:

       {
         "Name": "Archith's Business",
         "Website": "www.archithbiz.com"
       }

---

7. Request Headers Mapping
   • What Happens Here?
     Ensures required headers are included and formatted correctly.

---

8. Request Path Mapping
   • What Happens Here?
     Maps the API path from the Unified API to the API’s endpoint.

---

9. Does query have truto_skip_api_call set to true?
   • What Happens Here?
     Checks if the request includes a flag to skip the actual API call. This is useful for debugging or returning mock responses.
   • Example:
     • Input: GET /unified/crm/accounts?truto_skip_api_call=true.
     • Output: Skips the Salesforce API call and returns mock data:

       {
         "id": "mock-12345",
         "name": "Test Account"
       }

---

10. Call the Proxy API configured in the resource and method

• What Happens Here?
  Sends the actual request to the API (e.g., Salesforce).
• Example:
  • Translates:
    • Unified API: GET /unified/crm/accounts.
    • API: GET /services/data/v57.0/sobjects/Account.

---

11. Is there an error?
    • What Happens Here?
      Checks if the API returned an error (e.g., 404 Not Found or 500 Internal Server Error).

---

12. Error Mapping (if there's an error)
    • What Happens Here?
      Converts errors into a standardized format.
    • Example:
      • Salesforce Error:

        {
          "errorCode": "INVALID_FIELD",
          "message": "The field 'xyz' is not valid"
        }

      • Mapped Error for Unified API:

        {
          "error": "Invalid request. The field 'xyz' is not supported."
        }

---

13. Throw Error (if there's an error)
    • What Happens Here?
      Sends the mapped error back to the user and stops further processing.

---

14. Fetch Related Resources
    • What Happens Here?
      If additional data is needed, fetches them from the API. Usually this is used when the resource being fetched has parent-child relationship with another resource. For example, in Asana, workspace_id is needed to get the projects of that Workspace.

---

15. Response Mapping
    • What Happens Here?
      Converts the response into the Unified API’s format.
    • Example:
      • Salesforce Response:

        {
          "Id": "0012w000024KwDeAAK",
          "Name": "Truto",
          "BillingCity": "Bangalore"
        }

      • Unified API Response:

        {
          "id": "0012w000024KwDeAAK",
          "name": "Truto",
          "city": "Bangalore"
        }

---

16. Response Header Mapping
    • What Happens Here?
      Adds or modifies response headers for the Unified API.
    • Example:
      • Adds rate-limit headers:

        {
          "X-RateLimit-Limit": 1000,
          "X-RateLimit-Remaining": 995
        }

---

17. Are after steps configured?
    • What Happens Here?
      Checks if any "after steps" are configured for postprocessing the response.

---

18. Run after steps (if configured)
    • What Happens Here?
      Executes tasks like logging the response or triggering an event.
    • Example: Logs the response to an analytics tool.

---

19. Set result of after steps as Response
    • What Happens Here?
      Updates the response with the output from the after steps (if any).

---

20. Return the Response
    • What Happens Here?
      Sends the final, processed response back to the user.
    • Example Final Response:

      {
        "id": "0012w000024KwDeAAK",
        "name": "Truto",
        "city": "Bangalore",
        "phone": "123-456-7890"
      }