Download the Postman schemas
You can now build and use a unique HTTP connector to fit your exact needs. This connector will remain private for your use only and will be available in the Celigo platform (visible only to you) after it's created. Currently, you cannot add an image or logo to the connector. To build the connector:
-
Create the HTTP connector using Postman and the configured schemas.
This article goes over some of the concepts around building an HTTP connector.
An API is an application program interface exposed so users can interact with data in software. APIs enable the integration between different software products, allowing them to communicate with each other without needing to know the internal workings of each other's software. A connector can have multiple APIs associated with it. For example, Shopify has Partner APIs and Payment APIs. Both are mutually exclusive APIs designed for different purposes. Each API has its own resources and endpoints.
A connector is a preconfigured form that can connect to a third-party application. The Celigo platform has hundreds of preconfigured application, database, or universal connectors. This Postman collection allows you to create your own HTTP-based connector. A connector creates a link to a software application’s API. Then, you can use any available resources and endpoints to gather, modify, or delete data.
A resource typically refers to specific data or information accessible through an API or other integration mechanisms. Resources are the fundamental building blocks you interact with when integrating different systems or applications.
Resources are typically identified using resource identifiers within an API. These are used in API requests to specify which resource you want to interact with. For example, a URL like https://api.example.com/customers/ represents the customer resource, which can have multiple endpoints and methods.
Resources are usually represented in a specific data format, such as JSON or XML, which defines their structure and content when retrieved or sent through an API request.
An endpoint refers to a specific URL or URI (Uniform Resource Identifier) representing an application's unique location or resource. Endpoints are a fundamental concept in API design and usage, and they play a crucial role in defining how data and functionality can be accessed and manipulated.
Endpoints are typically represented as URLs or URIs. You can use these web addresses to send HTTP requests to interact with the API. For example, an endpoint URL in an application might look like: https://api.example.com/customers or https://api.example.com/products/123.
Endpoints are not only about where you send requests but also about how you interact with the resources. Different HTTP methods (GET, POST, PUT, DELETE, etc.) are used with endpoints to perform actions like retrieving data, creating new resources, updating existing resources, or deleting resources.
In practice, when working with an API, you specify the endpoint URL and use the appropriate HTTP method to interact with the desired resource. For example:
-
To retrieve a list of users, you might send a
GETrequest to the/usersendpoint. -
To create a new user, you might send a
POSTrequest to the/usersendpoint. -
To update an existing user's information, you might send a
PUTrequest to the/users/<id>endpoint, whereidrepresents the specific user's identifier.
A framework is like a bridge that fills the gap between our universal HTTP connector and external HTTP APIs, giving you a streamlined experience for creating connections, imports, and exports in the Celigo platform.
Before building a connector, it is essential to understand how to create metadata, preconfigured fields, and fields that a user must set.
Your metadata refers to data that provides information about other data. In this case, connector metadata consists of preconfigured fields and requirements that remain the same regardless of who created the connection or when it was created. For example, the application’s Base URI (if fixed) or the authentication type (if only one is available) can be set as metadata.
Here’s a simple exercise to help clarify how connector metadata is structured:
Imagine you’re working with an app that doesn’t have a prebuilt connector. To connect it, you would use a universal HTTP connection. Let’s walk through how two different users, User A and User B, might set up this connection.
-
User A successfully establishes the connection using the HTTP form.
-
User B performs the same task by filling in the required fields on the form.
If both User A and User B enter the same information in specific fields, these fields are considered preconfigured. You can set these fields up in advance for the connector, so users won’t need to fill them out manually. In other words, you'll configure these values in the connector metadata, and users won’t need to see or edit them.
Some fields will vary between users. For example, User A and User B may enter different information. You'll want users to fill in these fields when setting up their connection. We call these fieldsUserMustSet.
-
A version of the app or API
-
Credentials such as a token, username, or password
Learn more about a simple vs HTTP form view. Application-specific (simple) forms are based on the universal HTTP connector, including only the most common settings required for integrating with the application. In this view, you’ll see only the fields marked as fieldsUserMustSet. These are the fields where users need to provide specific input because their values can’t be preconfigured. By focusing on these fields, you reduce the cognitive load on users, allowing them to focus only on what’s necessary for the connection.
There are two types of fields you will encounter:
-
Custom Settings/Encrypted Fields: These fields are specific to the app and often require input that varies from user to user. Connector developers have full control over how these fields are presented and can include helpful text through the metadata to guide users. These fields often capture unique data like credentials or specific configurations needed for the app.
-
Standard HTTP Fields: These are the more common fields that users are accustomed to seeing, such as username, password, or token. Most apps follow similar naming conventions for these fields, and if the name is slightly different (like “Token” vs. “API Token”), you can reuse the field without changing its label. The goal is to maintain consistency and simplicity across the setup process without confusing the user with minor variations.
The HTTP view represents what a user would manually configure using a universal HTTP connection. It is automatically generated based on the provided metadata, including Preconfigured fields and fieldsUserMustSet. The HTTP view is designed for advanced users who may need to make custom modifications. Any changes made here may affect compatibility with the simple view.
The BaseURI is the key identifier for this form. If an advanced user changes the configuration, including the BaseURI, the Celigo platform will automatically match it to the correct connector. For example, if the BaseURI on Narvar’s HTTP view is changed to match UPS’s BaseURI, the Celigo platform automatically maps the connection to UPS.
Custom settings and common form fields are used to create fields a user can input into. Sometimes, only part of a field will vary between users. You can typically use custom settings in the following ways:
-
When the corresponding HTTP field has a partial value fixed (like the Base URI or Authentication URLs for OAuth); for example, in a Shopify connector, the base URL might look like this:
https://www.{{{storename}}}.myshopify.com. In this case, the part that varies is thestorename. Each user must enter their unique store name to complete the URL. You can handle this by creating custom settings, allowing users to enter the information unique to their situation. -
When the corresponding HTTP field cannot be presented as is, for example, the value for the License ID needs to be passed as an HTTP header. Asking a user to provide the License ID in the header's key-value format would not be pleasant. In this case, we can create a custom setting and assign its value to the user.
There are some situations where you wouldn’t want to use custom settings. Typically, authentication-related fields would not be ideal for custom fields. If the underlying application follows a standard authentication mechanism the Celigo platform already supports, you should reuse the available field. For example, the token authentication type is already supported and can be used as a fieldsUserMustSet field.
Comments
Article is closed for comments.