7: Resources

After you set up your element, you can add resources to start making requests. As you create new resources, keep the API documentation of the API provider close. You will refer to it often.

Certain resources automatically appear based on the hub. For example, if you create an element in the CRM hub, Cloud Elements creates endpoints resources like accounts, contacts, leads, and opportunities. The resources created differ from hub to hub, but we will always create the following resources:

• /ping
• /objects
• /objectName

Define New Resources

Defining a resource is a multi-step process, but you do not need to complete each step. For example, you need to add hooks only for advanced or complex use cases. You need to configure bulk for only the resources that you plan to download or upload bulk changes.

When defining resources, begin by adding a resource and providing basic information about the resource as a whole. For each endpoint, provide a description and add any endpoint-level configuration. If needed, add parameters to pass along with each request to each endpoint. For more complex use cases, write hooks needed to perform complex tasks. If the method requires models (POST, PUT, PATCH), define the models for each request and response. Lastly, if you want to be able to upload or download bulk CSV or JSON files, configure bulk for the endpoint.

Before you begin, review the Element Conventions so your element will align with others in the Elements Catalog.

Add a Resource with a Different API Type

You can now create a new resource with a different API type at the resource level by overriding the API type at the element level. 

For example, the Adwords element is a SOAP API for all its resources except the /reports resource. The API type of the element was overridden at the resource level, making /reports a REST API resource. 

Here's a use case for the same.

Add a Resource

Adding a resource enables you to create multiple endpoints for a single resource at one time. You can also add individual endpoints one at a time. Cloud Elements automatically groups individual endpoints by resource name when they match.

To add a resource:

1. Click Add a new resource at the top of the page.
2. Identify if the resource is a child resource, such as /users/{id}/tasks or /contacts/{id}/tasks.
3. In Cloud Elements Resource Name add the name of the resource as you want to see it in Cloud Elements. For example, enter deals to add a /deals resource to a CRM element. The name you choose is what appears in the API documentation and also creates an endpoint in the hub. For example, the new GET /deals endpoint appears as GET /deals in the docs and is accessible via the hubs/crm/deals endpoint. 
   Note: To remain consistent with Cloud Elements naming conventions, we recommend that you name the resources in the plural form. For example, `/deals` not `/deal`.
4. In Vendor Resource Name add the path to the resource at the API provider. The value that you enter is appended directly to the Base URL. If your Base URL ends with a slash / then do not enter a slash before the resource name. If your Base URL does not end in a slash /, then add one before the resource name.
5. In Primary Key enter the property that uniquely identifies the resource. Primary keys are typically ID fields associated with the resource. In this example, a primary key could be id.
6. In Created Date Key and Updated Date Key enter the properties that identify the created and updated dates. Created and updated date keys vary widely, but can be created, createdate, or timecreated and updated, lastModified, or dateModified.
7. Select the methods to add. You will define the methods that you select when you set up the endpoints. Make sure that the methods that you select are supported by the API provider.

   For a new deals resource with all methods, our basic resource information looks like this:
   

   

8. Click Go.
9. Continue to Configure Endpoints.

Configure Endpoints

After you provide the basic information to create a resource, Cloud Elements shows the endpoints associated with each method that you chose to configure for the resource in an editable API documentation format. Use the Endpoints tab (highlighted below) to configure each of the endpoints created from the combination of the resource and the methods that you selected in the previous step. If you did not select the correct methods in the previous step, you can add or remove endpoints on the Endpoints tab. 

If you have any authenticated element instances for the element, they appear on the left. Select an element instance to test the endpoints as you build them.

To set up endpoints:

1. Click

   

2. Expand the Configuration section.

   

3. In Resource Type select a resource type other than API only if you want to alter how the API documentation treats the endpoint.
4. Add a Root Key to identify the top level field of the resource and limit what you send (Request Root Key) or receive (Response Root Key). For example, if you receive the following payload, but only want items, not numberOfItems and items, enter items.

   
   

   
   {
     "numberOfItems": 10,
     "items": {
       "itemOne" : "hello",
       "itemtwo" : "world"
     }
   }

   
   

5. In Pagination Type select to override the default pagination settings of the element. If you select nothing, the default is Supported.
   Note: If the API provider does not support paging, Cloud Elements uses the `page` or `nextPage` and `pageSize` parameters to page through the result set.
6. In Next Resource select another endpoint if your use case requires requests to multiple endpoints one after another.
7. Enter a description. This appears in the API documentation and should help a user understand what the request is for and what to expect in the response. A description of the GET /deals endpoint could be: "Retrieves a list of deals. Use CEQL to filter by related fields like company and contact."
   Tip: The descriptions that you enter for each endpoint should help a user understand what the endpoint does. Keep the descriptions short, no more than three sentences. Start with a verb associated with a method like gets, retrieves, checks, creates, returns, updates, or deletes. Then describe what resource is being manipulated and add any other helpful information about required fields, filtering, or formatting.
   8. Continue to Add Parameters.

Endpoint Configuration Parameters

Add Parameters

Endpoint parameters allow you to pass various properties to the endpoint. Use the endpoint parameters to configure searches, pagination, ids, and required fields. You can configure most required and optional parameters for most endpoints. Cloud Elements provides some default common parameters for each method, except DELETE.

Default Parameters for Each Method

Map parameters that you send as part of the request from Cloud Elements on the top row to parameters available to the resource at the API provider on the second row. 

To define a parameter :

1. Select an endpoint, and then click

   

2. If you need to add a parameter, click Add New Parameter.
3. In Parameter Name, enter the name of the parameter. The name appears in the API documentation in some cases or can be a value passed to the API provider.
4. In Vendor Name enter the name of the parameter to map to. For example, if you are adding an id parameter, Vendor Name should be the unique id field for the resource like dealId.
5. In Parameter Type select the source of the parameter.
6. In Vendor Type select how the API provider receives the parameter.
7. In Parameter Datatype and Vendor Datatype select the data type of the parameter.
8. If the Parameter Type is body, enter the name of an existing model in Model Name. See Add Models to create a model for the endpoint.
9. If you want to switch the standard workflow where the parameters on the left are part of the request, click Parameter Source, and then select Request. ID, GET,
10. To make the parameter a required part of the request, switch Required on.
11. In Parameter Description enter a brief description of the parameter. If the parameter appears in the API documentation, this description also appears.
12. Click Save:
    • If you need to add any more endpoints, continue to Add Endpoints.
    • If the resource requires more logic to interact with it, continue to Add Hooks.
    • if you need to add a model to a POST, PUT, or PATCh request, continue to Add Models
    • If you need to be able to upload or download bulk data in JSON or CSV format, continue to Configure Bulk.

Parameters

Add Hooks

You can create resource hooks to manipulate any part of a request or response or to operate on a configuration. Resource hooks work differently than global hooks because they happen only on requests and responses related to a specific endpoint. Custom Hooks provides detailed information about using hooks and includes examples.

To create a resource hook:

1. In the endpoint edit view, click Add a pre-request hook or Add a post-response hook depending on what you need to manipulate.
2. Write the script needed for your use case. See Custom Hooks for more information about the functions and libraries available to you.
3. Save the endpoint.

Add Models

Depending on the endpoint method, you can add request models and response models. Request models provide an example of how you should structure the JSON body of a POST, PUT, or PATCH request. Response models give you an idea of what the response from the API vendor should look like.

Request models are required for POST, PUT, or PATCH requests, and the model that you set up should match the Model Name in the body parameter.

You can add request models in two ways: entering the model schema directly or generating the model schema from a sample payload.

To add a model:

1. Identify what the request body should look like in the API provider's documentation or acquire a sample payload.
2. Click Request Model or Response Model.
3. Enter a name for the model.
4. Depending on how you want to enter the model:
   • Enter the model as a schema object as defined in the OpenAPI version 2.0 Specification.
   • Or, click Generate from Sample Payload, paste the sample payload, and then click Generate.
     

     

5. Click Save.

Sample Model

The following sample model is a request model called postDeals for a deals resource.

{
    "postDeals": {
        "id": "postDeals",
        "properties": {
            "deal": {
                "type": "deal"
            }
        }
    },
    "deal": {
        "id": "deal",
        "properties": {
            "owner": {
                "type": "string"
            },
            "stage": {
                "type": "string"
            },
            "contact": {
                "type": "string"
            },
            "currency": {
                "type": "string"
            },
            "title": {
                "type": "string"
            },
            "percent": {
                "type": "unknown"
            },
            "value": {
                "format": "int32",
                "type": "integer"
            },
            "group": {
                "type": "string"
            },
            "status": {
                "format": "int32",
                "type": "integer"
            }
        }
    }
}

Configure Bulk

You can set up each resource to be able to upload and download bulk data in either jSON or CSV format.

To configure bulk:

1. Click the Bulk tab.
2. Select to enable bulk upload, download, or both.
3. In each of the fields, select the format that the endpoint expects.
4. Click Save Bulk Configuration.

Add Endpoints

You can add a new endpoint for a resource.

To add an endpoint:

1. Under the last endpoint associated with the resource, click Add a new endpoint.
2. Select the Method for the new endpoint. The left side represents the Cloud Elements side of the endpoint.
3. On the right side, select the vendor method associate with the endpoint, and then enter the URL of that endpoint.
4. Click Go, and then follow the steps to define the resource.

Delete Endpoints

If you no longer need an endpoint, click , and then confirm the deletion. To completely remove a resource, delete all of the endpoints associated with it.

Copy Endpoints

To copy an endpoint, click . After you copy and endpoint, Cloud Elements creates a new resource and endpoint with the word _copy appended to it.

Chaining Resources

You can create sequences of requests and perform operations based on the results of earlier requests in a sequence. Data from earlier resources in a chain are available to hooks through the request_previous_response and request_previous_response_headers parameters. Data is also available to parameters in the prevBodyField and prevBody Parameter Types.

To chain requests start with the earliest requests in the chain. While working with the endpoint configuration, select the next resource in the chain from the Next Resource list.