Manage Custom Endpoints

Custom endpoints are RESTful endpoints that do not require mapping to a specific data model and can return JSON, HTML, or XML responses and binary data.
You can build services, sometimes unrelated to your database objects, with custom endpoints. Custom endpoints are RESTful endpoints that do not require mapping to a specific data model and can return JSON, HTML, or XML responses and binary data. By default, they are not subject to security, but you can require that requests to your custom endpoint have a client authentication token.
The following video demonstrates how to create and test a simple custom endpoint for your API in API Creator using JavaScript:
You can play the video in full screen by clicking the YouTube logo to the right of the Settings icon that displays at the bottom of the video.

In this article:
Create a Custom Endpoint
  1. 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.
  2. 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
    Your custom endpoint displays in the list.
  3. Complete the following fields, and then click
    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,
    Layer7 Live API Creator
    invokes the first one it finds.
    Best Practice:
    Ensure that your URL patterns do not overlap.
    The handler operations for this custom endpoint. For example, the custom endpoint can invoke entities and resources using the methods that are included with the
    object. For more information about these methods, see The SysUtility Object.
    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 JavaScript Code Examples.
    Select the verb for this custom endpoint.
    Indicates whether this custom endpoint is active. API Creator invokes only active custom endpoints. To deactivate your custom endpoint, clear this field.
    Indicates whether requests to your custom endpoint require a client authentication token.
The custom endpoint is created.
Extend Custom Endpoints to use Complex Authentication
You can extend your custom endpoint to use more complex authentication measures using the properties and methods that are included with the
  • For non-authenticated requests, the
    object is null.
  • You cannot issue calls such as
    . To use
    , your custom endpoint must indicate that requests to the endpoint require a client authentication token (the
    checkbox must be selected).
For more information about the
object, see The logicContext Object.
Run Custom Endpoints
You can run custom endpoints:
Run Custom Endpoints that Return JSON Responses
Layer7 Live API Creator
calls your custom endpoint for all URLs matching the contents of the URL. Your handler has access to the
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
variable is a Java Map. You can call GET and PUT on it. If you do not specify a response header,
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
variable. You can also include custom response codes and its description as part of your JSON response.
For more information about
, see the Oracle documentation.
Run Custom Endpoints with Payload in POSTs and PUTs
You can run custom endpoints with a payload in a POST or PUT request.  The following code snippet shows an example of how you can read the payload using the
method from the
variable (of type
within a POST or PUT request:
var IOUtils = Java.type("");
var StandardCharsets = Java.type("java.nio.charset.StandardCharsets");
var inputStream = request.getInputStream();
// get the payload
var result = IOUtils.toString(inputStream, StandardCharsets.UTF_8)
// add additional code to process payload
Run Custom Endpoints with URL-Encoded Payloads in POSTs
You can run custom endpoints with URL-encoded payloads by passing the parameters in the payload of a POST request. In the header, set the
of the request to
. Define the
variable. You can enumerate and get the parameter values using this variable.
The following example shows the payload and a POST request that creates the
custom endpoint.
if (formParameters && (typeof formParameters != 'undefined')) {
for each (var paramName in
.keySet()) {
var paramValues =
for each (var paramValue in paramValues) {
print("Param " + paramName + " has value: " + paramValue);
The following code snippet shows the POST request using cURL:
curl -d "arg1=hello&arg2=world" -X POST http://localhost:8080/http/default/demo/custEP
Run Custom Endpoints that Return HTML Responses
You can run custom endpoints that return an HTML response. For example, the following code snippet shows the code for creating a simple HTML page that returns the content:
responseHeaders.put('Content-Type', 'text/html');
API that is part of the Business to Business (B2B) sample includes the
custom endpoint. This custom endpoint creates a simple HTML page that includes the content:
var html = "<!DOCTYPE html>\n";
html += "<html>";
html += "<body>";
html += "<title>B2B Menu</title>";
html += "<p>Illustrates you can build simple html pages - no deploy";
html += "<p>.. See Custom Endpoints (disable Short Menus)";
html += "<h1>B2B Documentation</h1>";
html += "<a href='' target='_blank'>Docs</a>";
html += "<h1>B2B Execution</h1>";
html += "<a href='http://localhost:8080/DataExplorer/index.html#/?serverName=http:%2F%2Flocalhost:8080%2Frest%2Fdefault%2Fb2bderbynw%2Fv1%2F&forceLogin=true' target='_blank'>Run Data Explorer</a>";
html += "</body>";
html += "</html>";
responseHeaders.put('Content-Type', 'text/html');
return html;
To run this custom endpoint, copy the contents of the URL (in this example, http://localhost:8080/http/default/b2bderbynw/B2B.*) to a new browser tab.
The following image shows the results:
CA Technologies
Test your Custom Endpoint
You can test your custom endpoints using various methods, including: