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
- With your API open, in the Create section, clickCustom 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, clickCreate a Custom Endpoint.
- If you have at least one custom endpoint defined, on the Custom Endpoints page, clickAdd.
- Complete the following fields, and then clickSave:URL patternThe 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 Creatorinvokes the first one it finds.Best Practice:Ensure that your URL patterns do not overlap.CodeThe handler operations for this custom endpoint. For example, the custom endpoint can invoke entities and resources using the methods that are included with theSysUtilityobject. 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.VerbsSelect the verb for this custom endpoint.Options:GET, POST, PUT, DELETEActiveIndicates whether this custom endpoint is active. API Creator invokes only active custom endpoints. To deactivate your custom endpoint, clear this field.Default:SelectedAuthenticateIndicates 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, thelogicContextobject is null.
- You cannot issue calls such asresourceGet. To useresourceGet, your custom endpoint must indicate that requests to the endpoint require a client authentication token (theAuthenticatecheckbox 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 payloadvar 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 informParameters.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:

Test your Custom Endpoint
You can test your custom endpoints using various methods, including:
- 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.