Working with Visual Builder's Business Object REST API — Part 2: Create, Update, and Delete

In Part 1, we looked at accessing Visual Builder business object REST APIs. We focused on how to enable access, where to find the endpoints and resource descriptions, and reading the business object with a GET request. In the next part, we’ll look at CREATE, PATCH (update), and DELETE, which take a little extra setup.

Since GET (read) is a benign operation (meaning no creation or destruction of data), basic authentication is enough to provide access. In general though, for business object access, basic auth is a reasonable approach (compare with OAuth) because these types of operations are generally used for service to service interaction, rather than a specific user interacting with the business object via a user interface on a personal browser client. This means username/password are also generally stored within the backend and not on the client.

However, since CREATE, PATCH, and DELETE will touch the data and are potentially destructive, an additional requirement is needed to ensure the proper service (and not a hijack from cross-site scripting for example) is making the request. To allow a server to use these functions, Visual Builder needs to be made aware of the origin of the request. First, it must be whitelisted in the Visual Builder Administration page, and second, each request must include an ORIGIN header with the matching URL or IP address.

As mentioned, first we need to whitelist the service that wishes to make CREATE, PATCH, and DELETE calls. This is found in the Visual Builder Administration page, which is accessed via the hamburger icon at the top right of the service page.

Within that Adminsistration page, you will find an Allowed Origins settings pane, in which you can add a new IP or URL.

Click the New Origin button to add your server IP or base address.

Now you can make the POST, PATCH, or DELETE request by adding an Origin header to call that provides the matching IP or base address. The below example cURL for a CREATE call shows the origin IP. It also shows a new argument for the JSON payload that will be sent with POST and PATCH. The auth token has been obscured with “-” for security purposes.

curl -i -H "Authorization : Basic anQ-------------------1AQnIw" 
-H "Content-Type: application/vnd.oracle.adf.resourceitem+json" 
-H "Origin:http://my.server.com" 
-d @new_cust.json 
-X POST https://instance-iddomain.builder.us.oraclecloud.com/design/BOsAtREST/1.0/resources/data/Customer

You may notice a new argument -d in this cURL. -d is uses to specify a data file. new_cust.json is found in the local directory from which I am making the cURL request. The json payload is contains the name : value pairs for the new Customer entry. Below is an example JSON body for this business object.

{
     "name": "New Company"
     "state": "NY
}

For an UPDATE, the cURL looks almost identical, except it uses a PATCH command instead of POST and only the fields that will be updated should be in the JSON payload. Finally, you must specify which Customer by using the ID in the URL (which represents the primary key).

curl -i -H "Authorization : Basic anQ-------------------1AQnIw" 
-H "Content-Type: application/vnd.oracle.adf.resourceitem+json" 
-H "Origin:http://my.server.com" 
-d @new_cust.json 
-X PATCH https://instance-iddomain.builder.us.oraclecloud.com/design/BOsAtREST/1.0/resources/data/Customer/1

And for DELETE, no payload is required but you must again specify which row will be deleted by including the primary key in the resource endpoint.

curl -i -H "Authorization : Basic anQ-------------------1AQnIw" 
-H "Content-Type: application/vnd.oracle.adf.resourceitem+json" 
-H "Origin:http://my.server.com" 
-X DELETE https://instance-iddomain.builder.us.oraclecloud.com/design/BOsAtREST/1.0/resources/data/Customer/1