Articles in this section

Create and manage APIs using API builder

Kathyana Queeman
Updated
 

Use the API builder to create APIs with a visual, low-code interface. You can customize your API requests and responses, add new or existing lookups and imports from the Celigo platform, and easily define your business logic. You can also configure transformations, error handling, and mappings and test your API to ensure it works as expected. There are multiple ways for you to access the API Builder:

  • From the Home page, click Create → API at the top of the page.

    Create_from_home_page.png

  • From any page, click Resources → APIs.

    resources_api.png

    • If you have never created an API, click Create API at the center of the page or on the upper right side.

      API_list_with_no_APIs.png

    • If you have previously created an API, click Create API in the upper right side of the page.

      create_api_button_right_corner.png

  • From any page, click Build → API builder to create an API.

    tools_menu_API_builder.png

Create an API

  1. Click Create API from any of the locations listed above.

  2. In the new panel, choose API builder or JavaScript.

    Note

    This article covers the API builder. To create an API using JavaScript, see Create a JavaScript API.

  3. Name your API. For example, "Get a pet."

  4. Describe your API.

  5. Add your API version. The version defaults to v1, but you can change it. The API's URI includes the version as: https://api.integrator.io/apis/<version>.

  6. Create a new integration or add your API to an existing integration.

  7. Click Next to create your API.

Create_API_.png

Support for the following features in API integrations will be added at a later date:

  • Creating and managing JavaScript APIs.

  • Revisions and other Integration Lifecycle Management (ILM) features.

  • Managing API tokens from an integration.

  • Viewing API analytics and dashboards.

  • API error notifications.

  • Custom settings in APIs (JSON settings field).

  • Aliases for APIs.

Build an API

Building your API is easy with the API builder's low-code design.

Every newly created API includes one API request and two API responses. The two default API response steps are for success (200) and error (500) codes; however, you can add additional responses for APIs with multiple success or error codes.

API_builder_breakdown.png

Click the image to expand

  1. Build: API builder, where you can create and configure APIs.

  2. Connections: A list of all the connections used in your API and their status.

  3. Audit log: An audit log that records changes to an API resource.

  4. Test run: Test your API to ensure it's working as expected.

  5. Settings: Configure basic details about your API, such as name, description, and version. You can also copy your invoke URL, which invokes the API from an external application or testing tool like Postman. Finally, you can download the OpenAPI specification to give your customers detailed insights into the API’s structure, request/response formats, and authentication requirements.

  6. Actions overflow (...): Additional options for managing your API.

    1. View request logs: View and manage your request logs to handle errors appropriately.

    2. View audit logs: View and manage your API's audit logs.

    3. Push to APIM or View in APIM (API Management only): Push your API to your APIM console so you can add additional configurations and publish your APIs. If you've already pushed the API, an APIM label will appear next to the API on the API builder list page.

    4. Download OpenAPI spec: Download the OpenAPI spec automatically generated by the Celigo platform.

    5. Copy invoke URL: Invoke your API using the URL provided.

      Warning

      The invoke URL is only available after you configure your API request.

    6. Delete API: Delete your API. The API is sent to the Recycle bin for 30 days or until your data retention policy purges it.

    7. Disable API: You can disable the API to stop access to the API, for example, while testing or retiring the API.

      Warning

      Disabling an API may affect existing users who are reliant on that service.

  7. API request: Create your API request.

  8. Add a resource or branch: Add a lookup or import to configure your business logic. You can also add branches to customize your API.

  9. Added resources: Any lookups, imports, guardrails, tools, or AI agents you add will appear here.

  10. Actions overflow (...) (Step components menu): Add transformations, filters, and hooks. All available step components are listed in the order they would be executed if they were applied to the API step.

  11. Edit branches: Edit your branches to add routing logic.

  12. Response picker: An out-of-the-box branching router to define multiple response nodes and seamlessly handle different response codes and structures.

  13. API response: Create your API response.

Maintain an API

API_list_view.png

Maintaining an API after it's been created is very straightforward. The API builder tab lists all the non-JavaScript APIs you've created, including:

  • Name/Description: The name and description you gave your API when you created it.

  • Integration: Your API's integration.

  • Version: The version you gave your API when you created it. This can be changed in the API's settings in the API builder. The version is included in the API's URI as follows: https://api.integrator.io/apis/<version>.

  • HTTP method: The HTTP method you chose when you created your API request.

  • Relative URI: The relative URI you created when configuring your API request. This is relative to https://api.integrator.io/apis/<version>. Query parameters are excluded in this view.

    The API endpoint URL is publicly accessible and may be identical to an existing one in a different account. However, only users with a valid API token can successfully invoke it, ensuring secure access for the intended audience. The endpoint URL must be unique within your account – meaning that you can't have two identical endpoint URLs enabled simultaneously in the same account.

  • Off/On: You can disable the API to stop access, for example, while testing or retiring the API.

    Warning

    Disabling an API may affect existing users who are reliant on that service.

  • Last updated: The date and time your API was last updated.

  • Actions overflow (...): Additional options for managing your API. These are available for every API in the API list view or for a specific API in the API builder.

    • Edit API: Click this to open the API builder and edit your API as needed.

      Tip

      Alternatively, you can edit your API by clicking its name.

    • View request logs: View and manage your request logs.

    • View audit logs: View and manage your API's audit logs.

    • Push to APIM or View in APIM (API Management only): Push your API to your API console so you can add additional configurations and publish your APIs. If you've already pushed the API, an APIM label will appear next to the API on the API builder list page.

    • Download OpenAPI spec: Download the OpenAPI spec automatically generated by the Celigo platform.

    • Download API: You cannot clone or download a standalone API.

    • Copy cURL: Copy a cURL command to invoke your API. For example:

      curl -X GET "https://api.integrator.io/apis/v1/pets/sampleid?microchip_id=true" \
-H "Authorization: Bearer ********"

      Warning

      The cURL command is only available after you configure your API request.

    • Add to MCP server: Learn more about MCP servers.

    • Clone API: You cannot clone or download a standalone API.

    • Move to integration: Move your API to a new or existing integration.

    • Used by: Resources using or used by this API.

    • Delete API: Delete your API. The API is sent to the Recycle bin for 30 days or until your data retention policy purges it.

    APi_list_actions_.png

Clone an API

You can clone an API for versioning, testing, repurposing, or promotion to a new environment easily through the Celigo platform.

Note

Cloning or downloading integrations with APIs is not supported.

To clone an API:

  1. Navigate to Resources → APIs → API builder.

    resources_api.png

  2. From the API builder list view, find the API you'd like to clone and click Actions overflow (...) → Clone API. A new window will appear.

    – OR – 

    From the API builder, click Actions overflow (...) → Clone API. A new window will appear.

    Clone_API_Actions_menu_.png

    API builder list view

    canvas_clone.png

    API builder

  3. Add a unique name for your cloned API.

    clone_API.png

  4. Environment: Select an environment to clone your API into. Learn more about multi-environment management. This option is unavailable for accounts that do not have multiple environments enabled.

  5. Version: Add a version for your cloned API. 

    Note

    API Builder enforces version control by requiring unique combinations of HTTP method, version, and relative URI per environment (when using the new multi-environment management feature). In the case of the standard Sandbox-Production environment setup, the unique combination is enforced across both the environments, as API tokens are shared across these environments.

  6. Description (optional): Add a description for your cloned API.

  7. Review your API resources. Your resources (APIs, lookups, and imports), branching, filters, and transformations are all cloned.

    Clone_API_-_resources.png

  8. Click Clone API to continue.

  9. Configure your connection details. You can use existing connections or create a new one.

    Clone_API_-_configure_connections.png

Delete an API

After an API is deleted, it is placed in the recycle bin and purged according to your organization’s data retention period.

If the API has been pushed to the API Management console, deleting it may affect existing API consumers relying on it. You must update the API and the OpenAPI specification in the API Management console.

To delete an API from the API builder list view:

  1. Click Resources → APIs → API builder.

  2. Find your API in the list and click Actions overflow (...) → Delete API.

To delete an API from the API builder:

  1. Click Resources → APIs → API builder.

  2. Select the API you'd like to delete.

  3. In the API builder on the top right-hand side, click (...) → Delete API.

Authenticate and invoke an API

You can invoke an API using a third-party tool (like Postman) with cURL and an API token. You never need to include any form of authentication in custom headers. All APIs created in the Celigo platform automatically include token authentication and require an API token to be invoked externally. You can use other methods of authentication (like JWT or OAuth 2.0) with API Management, but you must manually update the OpenAPI schema in the API Management console.

Warning

The cURL is only available after you configure your API request.

To copy your invoke URL:

  1. Navigate to Resources → APIs → API builder → <Your API>.

  2. In the API builder, click Actions overflow (...) → Copy cURL copy.svg​​.

    actions_overflow_in_builder.png

    Actions overflow menu in the API builder

To generate an API token, see Managing API tokens. You can create a custom API token that only applies to specific APIs or a token that has full access to your Celigo platform account.

Limits and requirements

The following limits and requirements apply to requests and responses:

Request content size

Your Request content size cannot exceed 5MB.

Concurrency and global rate limit

The concurrency level set in your connections does not apply to API requests. However, the application you're connecting to may have its own rate limits. You can trigger the same API multiple times in parallel but are restricted by the global rate limit defined in Celigo's APIs. Your API(s) are rate-limited using a leaky-bucket algorithm with a bucket size of 1,000 and a fill rate of 300 tokens every second, allowing up to approximately 1,080,000 requests per hour.

The concurrency level property available in connection configurations applies only to flows, not APIs. The flow engine leverages an inbuilt queueing system where this concurrency level is managed, allowing it to pace work within those limits. The API engine, on the other hand, is optimized for low-latency processing, which bypasses this queueing system.

For example, let’s say you set a connection concurrency level to five (5) in the Celigo platform. This limit is ignored when creating the API; however, the application you're connecting to may have a maximum concurrency of 15. This can return an error if the concurrent requests made to that application exceed that limit.