1
Info
2
Properties
3
Authentication
4
Config & Parameters
5
Hooks
6
Events
7
Resources
When you create an element using Element Builder, the first step is to provide some basic information about the element. To build the element, we need to know how you identify the element, the hub it belongs to, the type of service to connect to, the authentication type of the element, and information about the API provider.
Element Information Setup
To complete the element information:
- Name and describe the element:
- Element Name — The name appears on the element card and should identify the API provider associated with it.
- Element Key — Generated from the Element Name by default, but you can enter any text. API requests use the element key, so make sure that it identifies the element.
- Description — The description helps to clarify the purpose of the element. The description appears in the response when you authenticate an instance of the element.
- Choose the hub associated with the new element —or enter a name for a new hub, and then click Create Option {Hub Name}. Make sure that you choose an accurate hub because you can leverage existing hub resources when you add resources to the element.
- Select the API type used by the API provider. You can find the API type in an Overview or Introduction section of the API documentation.
- REST API — Select if the API is a REST or RESTful API.
- SOAP API — Select if the API is a SOAP API.
- Database — Select of the API is for a database application.
Select the type of authentication needed to connect with the API provider. You can typically find this information in an Authorization or Authentication section of the provider's API documentation.
Note: Your authentication selection affects the configuration values that you will need to complete when you configure the element.Add reference information that you will need while building the element:
- Documentation URL — Add a link to the API documentation. You will reference this throughout the element building process.
- Vendor API Version — Add a version number here if available so you always know what version of the API the element was built for.
Optionally upload an image to associate with the element.
Note: Cloud Elements accepts .jpg, jpeg, .png, and .gif image files.Click Save & Next.
Continue to the next step, Element Builder Properties, or for more context about the Information tab and how its parameters relate to the element building process, see our supplementary documentation.
Element Information Parameters
| Parameter | Description | Required |
|---|---|---|
| Element Name | The name of the element. This helps form the default Element Key. | Y |
| Element Key | A unique identifier for the element. The Element Key must be alphanumeric and lower case. The default comes from the Element Name. The Element Key is used in /elementsendpoints that require {keyOrId}. | Y |
| Hub | The hub to which the element belongs. A collection of elements where the APIs of those elements have been normalized to a standard defined by the Hub. | N |
| Service type | Identifies the kind of element that you are building, either REST, SOAP, or database | Y |
| JSON REST API — for REST or RESTful APIS | ||
| SOAP/XML — for SOAP APIs | ||
| Database — for APIs provided by database applications. | ||
| Authentication Type | The authorization type used by the API provider. Find this in the API docs under Authorization or Authentication. | Y |
| Basic — Integrations authenticate with the API provider via user name and password. | ||
| OAuth 1.0 — Integrations authenticate with the API provider via OAuth 1.0. OAuth 1.0 does not require users to expose their credentials. OAuth 1.0 is a three step authentication process. The OAuth 1.0 protocol involves signing the payload on every request and thus is used by many financial services. While OAuth 1.0 provides a standard way to authenticate, many cloud services implement it in unique ways. Cloud Elements implements OAuth 1.0 to the specification defined at OAuth 1.0 specification. | ||
| OAuth 2.0 — The OAuth 2.0 protocol lets external applications — your application or Cloud Elements — request authorization to access and update a users data without asking users for sensitive user names and passwords. OAuth 2.0 is not strongly specified and many API providers implement it differently, so make sure that you read the API provider's documentation. Cloud Elements implements OAuth 2.0 to the specification defined at OAuth 2.0 specification. | ||
| AWS V2 — Amazon Web Services Signature Version 2 for older AWS resources. | ||
| AWS V4 — Amazon Web Services Signature Version 4 for the latest AWS resources. | ||
| Custom — For user-defined authentications, such as passing an API key in the header or login requests made during authentication where tokens are passed. Because OAuth 1.0 and 2.0 are implemented differently at different cloud services, you might need to choose Custom. | ||
| Documentation URL | The URL to the API provider's API documentation. | N |
| Vendor API version | Some vendors offer multiple versions of their API. Enter the version that you are building the element for here. | N |
| Base URL | Endpoints are appended to the base URL. So, with an endpoint like https://api.example.com/v1/users?role=admin&status=active, the base URL is https://api.example.com/v1/. Many API providers explicitly state the base URL, but in some cases you can find it by looking at examples in the API documentation. | Y |
| Pagination Max | The maximum number of records the API provider returns in a response. | Y |
| Pagination Type | How the API provider provides pages of data. Find the pagination types in a Pagination section of the API documentation. | Y |
| Page starts with n — Pagination begins with either 1 or 0. | ||
| Offset — A numeric offset identifies the first page. | ||
| Cursor — A unique key element identifies the first page entry |
