Articles in this section

Create and manage APIs using API builder

Kathyana Queeman
Updated

Note

These articles cover the low-code API builder tool. You can also work with JavaScript APIs. This feature is only available for Professional and Enterprise customers who are account administrators or owners.

 

New API builder user interface 

 

Create your first API

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 Tools → API builder to create a new 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. Click Next to create your API.

Create_API_.png

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. New UI: Toggle between the old and new UI.

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

  3. 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.

  4. 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.

  5. API request: Create your API request.

  6. ... (Tools menu): Add transformations, filters, and hooks. All available tools are listed in the order they would be executed if they were applied to the API step.

  7. Add a destination/lookup or Add branching: Add a lookup or import to configure your business logic. You can also add branches to customize your API.

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

  9. Destination/lookup: The lookup or import that executes your API. Without a destination or lookup, your API cannot be executed.

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

  11. API response: Create your API response.

  12. Run console: You can watch an API as it's running and access the errors as they're reported (even before the API run has been completed) using the Run console. The Run console appears on the first tab. You can see detailed information for each step in the API as it runs. Learn more about the Run console.

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

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

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: The name you gave your API when you created it.

  • 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.

  • 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.

    • Copy invoke URL (only in the API builder): Invoke your API using the URL provided.

      Warning

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

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

    • 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.

    APi_list_actions_.png

    Actions overflow menu in the API builder list view

    actions_overflow_in_builder.png

    Actions overflow menu in the API builder

Clone an API

You can clone an API for versioning, testing, repurposing, or promotion to a new environment easily through the Celigo platform. 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 the invoke URL 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 invoke URL 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 invoke URL 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.