Work with Endpoints to Access Business Objects

Apps in your visual application and other clients access your business objects through REST endpoints, which are available to you through a business object’s Endpoints tab.

View a Business Object's Endpoints

To view the endpoints for your business object:
  1. Select the business object in the Business Objects tab in the Navigator.
  2. Open the Endpoints tab for the business object.
    If you can't view endpoints, the business object is likely missing a resource file that defines endpoints, or its source file is corrupt (say, because of invalid syntax or merge conflicts in a Git repository).
    • If you see a message that there's no resource for a business object, click Create Resource to create a business-object-name.json file that defines the default endpoints.
    • If you see a message that endpoints cannot be displayed because of errors in the source file, click Open Source Editor and resolve the issue.

About the Endpoints Tab

For each business object, the Endpoints tab displays information about the endpoints you can call in code.



Resource APIs

The Resource APIs node displays the URLs you can use to retrieve business object metadata and data.
  • Use the Metadata URL to retrieve metadata about the business object using its /describe endpoint.
  • Use the Data URL to modify business object data through CRUD operations.

It's important to use the correct URLs for each phase of your visual application. Development URLs are meant to be used only during your app's development phase. This URL is a pointer to your app's design-time version (as indicated by /ic/builder/design/{app-name}/{app-version}/ in the path) and is simply a preview of your app. It is not meant to allow access to your app from other apps or tools. For example, you might copy the development metadata URL and use it with REST API tools similar to Postman to test the metadata URL during development.

To access business object metadata or data after your app is deployed, you need the application's staged or live URLs, which you can retrieve from your environment's Visual Builder instance. The staged URL points to the runtime version of your app, something like https://{host-name}/ic/builder/rt/{app-name}/{app-version}/, and can be used to access the business object APIs from other apps or tools. The live URL points to your application's permanent URL, something like https://{host-name}/ic/builder/rt/{app-name}/live/, where live replaces {app-version}.

Resource Cache Control

The Resource Cache Control node displays the caching strategy used to store the business object's data. See Control Data Caching for Business Objects.

Endpoints

The Endpoints node displays the business object's endpoints in a tabular format. The display includes the HTTP method, the endpoint URI, an endpoint name that you can use in code, and a description of the endpoint. A filter field at the top of the page allows you to view a subset of the endpoints.

For each business object, five default endpoints are created:

  • Two GET endpoints, to retrieve one or all business object instances
  • A POST endpoint, to create a business object instance
  • A PATCH endpoint, to update a business object instance
  • A DELETE endpoint, to delete a business object instance

If the business object refers to other business objects, endpoints that enable you to retrieve, create, delete, and update those business objects are also provided. You can control the endpoints exposed for each business object by adding or removing them in a resource editor (see Add or Remove Exposed Endpoints).

You can click an endpoint in the list to view the endpoint’s details, for example, details about the endpoint’s settings and the headers sent in the request. The details are displayed in read-only mode, but you can use the Test tab to see the response to requests sent with parameter values that you supply.


Description of bo-endpoints-details.png follows
Description of the illustration bo-endpoints-details.png

Note:

The REST endpoints for business objects support using URL parameters when retrieving resources, for example, to filter payloads using a query parameter to control the behavior of the data retrieved.

Add or Remove Exposed Endpoints

When your application has many inter-related business objects, you can add or remove endpoints that these business objects expose. Tailoring the endpoints to expose only those that you require controls the size of the metadata file that describes your endpoints and maximizes application performance, both at design time and runtime.

Endpoints for a business object are generated by traversing accessors in a tree structure. By default, only the first level of accessors (those owned by the business object) are added to the object's resource definition. You can change this default definition to add deeper endpoints when related objects are nested several levels down or to remove unwanted endpoints.

Let’s say your application uses the Employee, Department, Location, and Project business objects, which refer to one other as follows:
Description of bo-endpoints-edit-relationship.png follows
Description of the illustration bo-endpoints-edit-relationship.png

With this relationship, the first level of accessor endpoints for the main Employee object (/departmentObject and /projectObject) are included by default in the Employee object's resource definition. Other deeper endpoints are not included. Now, if you want to show the department and location names in a Table of Employees, you need to add endpoints that are not included by default, but which are required to expose this data. For example, you must add the nested /departmentObject/locationObject endpoint (not selected by default) to show an employee's location.

Optionally, if you want to restrict access to employee project information, you can remove the /projectObject endpoint (selected by default).

To select the endpoints you want to expose for a business object:

  1. Open the business object's Endpoints tab.
  2. In the Endpoints node, click Edit Endpoints.
  3. In the Business Object Resource Editor, drill down to each related business object to view available endpoints. The endpoints are uniquely identified by their accessors, enabled when one business object references another (see View, Create, and Edit Business Object Relationships).
  4. For each related business object, select or deselect endpoints to add or remove them.


    By default, only endpoints that are one level down from the parent node are selected. This example adds the deeper Employee/departmentObject/locationObject endpoint and removes the Employee/projectObject endpoint.

  5. Click Save. To take the default setting, click Apply Defaults.