1: Information Tab

1
Info




2
Properties




3
Authentication




4
Config & Parameters




5
Hooks




6
Events




7
Resources


When you create an adapter using Adapter Builder, the first step is to provide some basic information about the adapter. To build the adapter, we need to know how you identify the adapter, the hub it belongs to, the type of service to connect to, the authentication type of the adapter, and information about the API provider.

Adapter Information Setup

To complete the adapter information:

  1. Name and describe the adapter:

    • Adapter Name — The name appears on the adapter card and should identify the API provider associated with it.
    • Adapter Key — Generated from the Adapter Name by default, but you can enter any text. API requests use the adapter key, so make sure that it identifies the adapter.
    • Description — The description helps to clarify the purpose of the adapter. The description appears in the response when you authenticate an instance of the adapter.
  2. Choose the hub associated with the new adapter —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 adapter.
  3. 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.
  4. 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 adapter.
  5. Add reference information that you will need while building the adapter:

    • Documentation URL — Add a link to the API documentation. You will reference this throughout the adapter building process.
    • Vendor API Version — Add a version number here if available so you always know what version of the API the adapter was built for.
  6. Optionally upload an image to associate with the adapter.

    Note: Sugar Integrate accepts .jpg, jpeg, .png, and .gif image files.
  7. Click Save & Next.

Continue to the next step, Adapter Builder Properties, or for more context about the Information tab and how its parameters relate to the adapter building process, see our supplementary documentation.

Adapter Information Parameters

ParameterDescriptionRequired
Adapter NameThe name of the adapter. This helps form the default Adapter Key.Y
Adapter KeyA unique identifier for the adapter. The Adapter Key must be alphanumeric and lower case. The default comes from the Adapter Name. The Adapter Key is used in /elementsendpoints that require {keyOrId}.Y
HubThe hub to which the adapter belongs. A collection of adapters where the APIs of those adapters have been normalized to a standard defined by the Hub.N
Service typeIdentifies the kind of adapter that you are building, either REST, SOAP, or databaseY

JSON REST API — for REST or RESTful APIS

SOAP/XML — for SOAP APIs

Database — for APIs provided by database applications.
Authentication TypeThe 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. Sugar Integrate 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 Sugar Integrate — 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. Sugar Integrate 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 URLThe URL to the API provider's API documentation.N
Vendor API versionSome vendors offer multiple versions of their API. Enter the version that you are building the adapter for here.N
Base URLEndpoints 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 MaxThe maximum number of records the API provider returns in a response.Y
Pagination TypeHow 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 adapter identifies the first page entry