CA Live API Creator 5.0

5.4 5.3 5.2 5.1 5.0 4.1 4.0 3.2 3.1.1 3.1
English

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:
3
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
      Add
      .
    Your custom endpoint displays in the list.
  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,
    CA Live 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. For example, the custom endpoint can invoke entities and resources using the methods that are included with the
    SysUtility
     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.
    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 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
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 Responses
CA Live 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 a payload in a POST or PUT request.  The following code snippet shows an example of 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
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
Content-Type
 of the request to
application/x-www-form-urlencoded
 . Define the
formParameters
 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
custEP
 custom endpoint.
Payload
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);
        }
    }
}
Request
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');
Example:
The
B2B NW
 API that is part of the Business to Business (B2B) sample includes the
Menu
 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='https://docops.ca.com/ca-live-api-creator/5-2/en/tutorials-and-samples/b2b-api-sample' 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: