Configure and validate business objects as API endpoints in Jitterbit App Builder

Introduction

This page shows you how to expose a business object as an API endpoint, how to create custom validation rules for data posted to that endpoint, and how to test the complete configuration using an external API client.

Part 1: Configure the API Endpoint

This section covers the prerequisite steps to expose an application business object as an API.

1. Create an API key security provider

To authenticate against the API, you first need a security provider. Follow these steps:

1. Select IDE > Security Providers.

2. Under User Authentication, click + User Authentication. The Provider page opens.

3. Configure the provider with these settings:

   • Name: Enter a descriptive name, such as API Key.

   • Type: Select API Key.

   • Enabled: Select to enable the provider.

4. Click Save.

5. (Optional) Under Properties, click + Property to add and configure optional parameters for your API key.

2. Define an application endpoint

Next, you need to create an access point for your application. Follow these steps:

1. Select IDE > REST APIs.

2. Click Manage Endpoints. The Application Endpoints popup opens showing accessible applications and their endpoints.

3. Locate the application you want to expose and click its Edit icon.

4. Enter a name for the endpoint, such as endpoint-example.

5. Click the icon (or the Proceed button) to save the endpoint name.

6. Close the Application Endpoints popup. A new entry for the endpoint appears under Application.

3. Publish a business object endpoint

Now you can publish a specific business object (such as a table) from your application. Follow these steps:

1. On the REST APIs page, with your application selected, click the + Resource button in the Resources section. The Resource popup opens.

2. Set the following values:

   • Table: Open the menu and select the table you want to expose.

   • Endpoint: Enter a name for the table's endpoint.

3. Click Save, then close the Resource popup.

4. To find the full URL for your new endpoint, locate your application in the Application panel and click the Doc icon. This opens a report containing the API endpoint's documentation.

5. Scroll through the documentation to find the URL for the business object endpoint you just created. Copy this URL to use later.

4. Generate a user-specific API key

The final configuration step is to generate an API key for a user, allowing them to authenticate. Follow these steps:

1. Select IDE > User Management.

2. Under Users, click Open record icon for the user you want to grant API access to. The User popup opens.

3. Expand the Authentication section and confirm that Login Type is set to Interactive.

4. Select More > Keys. The Keys popup opens.

5. Click Create. The Generate Key popup opens.

6. Set values for the following:

   • Provider: Select the security provider you created in the first step (for example, API Key).

   • (Optional) Description: Enter a description for this key.

7. Click Save. App Builder automatically generates a value for the key. Copy the generated key value to use for testing.

   Important

   Ensure you have copied the key before closing the Generate Key popup, as it can not be shown again.

Part 2: Create a custom validation rule

This section covers how to create and apply a custom rule to validate incoming data before it is saved. This example creates a rule that prevents a record from being saved if its Required Date is in the past.

1. Create a business rule for validation

Follow these steps:

1. Open your app and select App Workbench > Rules.

2. Click By Table, then select the table you are exposing (for example, Order).

3. Under Rules, click + Rule.

4. On the Rule page, configure the rule's basic properties:

   • Name: Enter a descriptive name, such as Validation: Date Not in Past.

   • Purpose: Select Validation.

   • Target: The table should already be selected (for example, Order).

5. Click Create.

6. Configure the rule's logic:

   • Select the Columns tab, then add the columns the rule needs. For this example, add Order ID and Required Date.

   • Select the Where tab, then add a clause to define the failure condition. For this example, to check if the required date is in the past, add a condition where Required Date is less than or equal to Now().

7. (Optional) Click Validate.

2. Attach the validation rule to an event

To make the rule active, associate it with an event on the business object. Follow these steps:

1. From App Workbench > Rules, with By Table selected, select the same table (Order in this example).

2. Click the Events icon for (in this example) Orders (Source). The All Events popup opens.

3. In the Save row, click Rule Event Detail.

4. Under Validations, click Register. The Validation popup opens.

5. From the Rule menu, select the validation rule you just created (Validation: Date Not in Past).

6. Configure the validation action as follows:

   • Binding: Select Implicit.

   • Failure: Select Fail on data returned.

   • Severity: Select Error.

   • Message: Enter the error message to display when the validation fails, such as The required date cannot be in the past.

7. Click Save.

Part 3: Test the API endpoint

This section covers how to test the endpoint using a third-party API client, such as Postman, to ensure it is working as expected.

1. Configure the Test Client

Follow these steps:

1. In Postman, create a new POST request.

2. In the URL field, paste the endpoint URL you copied from the API documentation.

3. Configure the authorization:

   • Select the Authorization tab.

   • For Type, select API Key.

   • For Key, enter X-API-Key.

   • For Value, paste the user API key you copied earlier.

4. Configure the request body:

   • Select the Body tab.

   • Select the Raw radio button.

   • From the format dropdown, select JSON.

2. Test the validation rule (failure case)

Follow these steps:

1. In the JSON body, paste a record to trigger the validation error. For this example, use a Required Date that is in the past.

   Example failure record

   {
       "OrderID": 11255,
       "OrderDate": "2014-05-26T00:00:00",
       "RequiredDate": "2014-05-20T00:00:00",
       "ShippedDate": "2014-05-28T00:00:00",
       "ShipCost": 1000.50,
       "ShipName": "Test Site",
       "ShipAddress": "508 Main Street",
       "ShipCity": "Harwich",
       "ShipState": "MA",
       "ShipZip": "02630",
       "ShipCountry": "USA",
       "AddedOn": null,
       "AddedBy": null,
       "EmployeeID": "0f9c520c-1890-11f1-b283-ab1e4a99c4ce",
       "ShipperID": "f4b1df98-188f-11f1-90ba-7a85ad06b57c"
   }
   

2. Click Send.

3. Review the response. You should see a validation error with the custom message you configured: The required date cannot be in the past. The record is not created.

3. Test the endpoint (success case)

Follow these steps:

1. In the JSON body, modify the data so that it is valid. For this example, change the RequiredDate to a date in the future.

   Example success record

   {
       "OrderID": 11255,
       "OrderDate": "2014-05-26T00:00:00",
       "RequiredDate": "2114-05-20T00:00:00",
       "ShippedDate": "2014-05-28T00:00:00",
       "ShipCost": 1000.50,
       "ShipName": "Test Site",
       "ShipAddress": "508 Main Street",
       "ShipCity": "Harwich",
       "ShipState": "MA",
       "ShipZip": "02630",
       "ShipCountry": "USA",
       "AddedOn": null,
       "AddedBy": null,
       "EmployeeID": "0f9c520c-1890-11f1-b283-ab1e4a99c4ce",
       "ShipperID": "f4b1df98-188f-11f1-90ba-7a85ad06b57c"
   }
   

2. Click Send.

3. Review the response. You should see a 200 OK status, and the response body should not contain a validation error.

4. To confirm, navigate to the data table in your App Builder application and verify that the new record was created successfully.