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
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.
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:
 
2
Add Custom Endpoints
  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 
      Add
      .
    A new custom endpoint displays in the list. The following image shows this page:
    authenticate.png
  3. 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:
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 payload
var 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 
Menu
 custom endpoint that returns HTML. The following image shows this custom endpoint:
CustomEPhtml.png
Run this custom endpoint by copying the contents of the URL to a new browser page, as shown in the following image:
CA Technologies
Test your Custom Endpoint
You can test your custom endpoints using the following methods: