Creating endpoints for Application Builder

Endpoints are custom functions that produce data for use by widgets and external systems. Endpoints can access entity data and external web services.

Creating endpoints in the IBM® Watson Explorer Application Builder administration tool can help you accomplish the following goals:

Reuse code for custom widgets. Widgets that need to share data or calculations can use the same endpoint.
Integrate external services, such as services from the IBM Watson™ Developer Cloud and AlchemyAPI, with Application Builder.
Refresh widgets asynchronously by invoking endpoints, and then rendering the resulting data via JavaScript (Ajax).
Expose Application Builder entity data to external systems.

Endpoints have the following characteristics:

An endpoint can be accessed internally by the application or externally from a URL call.
Endpoints are stateless blocks of code that can be accessed from any part of the application.
All calls to endpoints must be authenticated. Endpoints have access to the current_user method.

To create an endpoint:

In the Application Builder administrator tool, click the Endpoints tab from the header.
Click Create an endpoint.
In the ID field, enter an ID.
Note: The ID of the endpoint dictates the external URL and must be used to access the endpoint. Therefore, choose an appropriate ID. You cannot change the ID after the endpoint is created.
In the Description field, you can enter any text that you want, but some of the following suggestions could be helpful for reference:
- The purpose of the endpoint
- Data that the endpoint produces
- Required parameters
In the Configuration field, enter Ruby code for the endpoint.
Note: Methods that are part of the query API are suggested automatically. For example, enter entity_types( in the field, select an entity type, enter a closing parenthesis, and then enter a period (.), which suggests a list of query API methods that are available in that context. For more information, see Common Application Builder Query API Examples.
If you are unfamiliar with creating endpoints, you might find it useful to review the code examples by completing the following steps:
Note: For all the code examples, you must modify them as appropriate for your system.
1. Click the information icon (the letter I), which is shown to the right of the Configuration field.
2. Click the example for parameters, and then click Insert. Typically you validate and assign parameters to variables as the first step in the endpoint.
  Note: Parameters that you pass to the endpoint are contained within the params hash. These parameters can be used directly, but typically it is appropriate to create a variable for each entry in the hash.
3. Select the example for the query API, and then click Insert.
4. Select the example for the web service, and then click Insert.
5. Select the example for formatting data, and then click Insert. Typically, you format the output data into XML or JSON as the last step in the endpoint.
In the Test Endpoint section, enter parameter names and values, and then click Test endpoint. Parameters that you enter are not saved until you save the endpoint.
Click Save changes.
You can now call the endpoint. Code snippets that you can use to call the endpoint are at the bottom of the page.