Manage Custom Endpoints

While you define most endpoints as tables, views, stored procedures, or resources, you can build services, perhaps unrelated to your database objects, by defining custom endpoints. Custom endpoints are RESTful endpoints that do not need to map to a specific data model.

calac41

You can define custom endpoints that return JSON or HTML responses and binary data. By default, custom endpoints are not subject to security. You can indicate that requests to your custom endpoint require authentication.

The following video demonstrates how to create and test a simple custom endpoint for your API in API Creator using JavaScript:

To play the video in full screen, click the YouTube logo to the right of the Settings icon that displays at the bottom of the video.

In this article:

Add Custom Endpoints

With your API open, in the Create section, click Custom Endpoints
.

If your API does not have existing custom endpoints, the Welcome to Custom Endpoints page appears. If your API has existing custom endpoints, they are listed on the Custom Endpoints page.

Complete one of the following options:

If you have not defined any custom endpoints, on the Welcome to Custom Endpoints page, click Create a Custom Endpoint
.

If you have at least one custom endpoint defined, on the Custom Endpoints page, click Add
.

A new custom endpoint displays in the list. The following image shows this page:

Complete the following fields, and then click Save
:

URL pattern

The regular expression that is matched with the URL of the incoming request to call this custom endpoint. This expression must follow the conventions of Java regular expressions. If more than one custom endpoint matches the URL for the request, API Creator invokes the first one it finds.

Best Practice:
Ensure that your URL patterns do not overlap.

Code

The handler operations for this custom endpoint. You can access and insert JavaScript code examples into the code editor.

For more information about the code examples that are available for custom endpoints, see Code Examples.

Verbs

Select the verb for this custom endpoint.

Options:
GET, POST, PUT, DELETE

Active

Indicates whether this custom endpoint is active. API Creator invokes only active custom endpoints. To deactivate your custom endpoint, clear this field.

Default:
Selected

Authenticate

Indicates whether requests to your custom endpoint require a client authentication token.

Default:
Cleared

The custom endpoint is created.

Extend a Custom Endpoint to use Complex Authentication

You can extend an endpoint to use more complex authentication measures using the

logicContext

object.

For non-authenticated requests:

The

logicContext

object is null.

You cannot issue calls such as

resourceGet

. To use

resourceGet

, your custom endpoint must indicate that requests to the endpoint require a client authentication token (the Authenticate
checkbox must be selected).

For more information about the

logicContext

object, see The logicContext Object.

Run Custom Endpoints

You can run custom endpoints:

That return JSON.

With payload in a POST or PUT.

With URL-encoded payload in a POST.

That return HTML format.

Run Custom Endpoints that Return JSON

API Creator calls your custom endpoint for all URLs matching the contents of the URL. Your handler has access to the

request

object and can specify response headers, for example:

responseHeaders.put('Content-Type', 'application/x-acme-special-json');return JSON.stringify({  result: 'Hello',  uri: "" + request.getRequestURI(), // Partial path without host/port  url: "" + request.getRequestURL(), // Full URL  method: "" + request.getMethod(), // GET, POST, etc  pathInfo: "" + request.getPathInfo(), // /<account>/<project>/<path>  acceptHeader: "" + request.getHeader("Accept"), // Any HTTP header  fooParam: "" + request.getParameter("foo") // Gets value of e.g. ...?foo=123});

The

responseHeaders

variable is a Java Map. You can call GET and PUT on it. If you do not specify a response header,

application/json

is returned by default. For example, you can return custom response codes that are based on your business rules and can add them to the

responseHeaders

variable. You can also include custom response codes and its description as part of your JSON response.

For more information about

HttpServletRequest

, see the Oracle documentation.

Run Custom Endpoints with Payload in POSTs and PUTs

You can run custom endpoints with payload in a POST or PUT request.

The following code example shows how you can read the payload using the

getInputStream

method from the request variable (of type

HTTPServletRequest)

within a POST or PUT request:

var IOUtils  = Java.type("org.apache.commons.io.IOUtils");var StandardCharsets  = Java.type("java.nio.charset.StandardCharsets");var inputStream = request.getInputStream();// get the payloadvar result = IOUtils.toString(inputStream, StandardCharsets.UTF_8)// add additional code to process payload...

Run Custom Endpoints with URL-Encoded Payloads in POSTs

Pass the following parameters in the payload of a POST, as shown in the following code snippet. In the header, set the

Content-Type

of the request to

application/x-www-form-urlencoded

. You can enumerate and get the parameter values using the

formParameters

variable. Define the

formParameters

variable only if the request is a POST and the payload is URL-encoded.

if (formParameters && (typeof formParameters != 'undefined')) {    for each (var paramName in formParameters.keySet()) {        var paramValues = formParameters.get(paramName);        for each (var paramValue in paramValues) {            print("Param " + paramName + " has value: " + paramValue);        }    }}

For example, you can create the

custEP

custom endpoint using the previous code, and then test it using cURL:

curl -d "arg1=hello&arg2=world" -X POST  http://localhost:8080/http/default/demo/custEP

Run Custom Endpoints that Return HTML

Custom endpoints can return HTML. For example, you can create simple HTML pages and can return the content with the following code:

responseHeaders.put('Content-Type', 'text/html');

For example, the Business to Business (B2B) sample defines the

custom endpoint that returns HTML. The following image shows this custom endpoint:

Run this custom endpoint by copying the contents of the URL to a new browser page, as shown in the following image:

Test your Custom Endpoint

You can test your custom endpoints using the following methods:

API testing tools, such as Postman or cURL.

For an example of how to test your custom endpoints using cURL, see the "Run Custom Endpoints with URL-Encoded Payloads in POSTs" section.

Copy the contents of the URL to a new browser page.

The REST Lab.

For more information about how to test your custom endpoints using the REST Lab, see Test your API Using the REST Lab.

Customize your API

CA Live API Creator 4.1

Manage Custom Endpoints