Custom Endpoints

You can define your own RESTful endpoints by adding custom endpoints. These handlers are free-form and do not need to map to a specific data model. You can implement functionality and return a JSON or HTML response using custom endpoints that include JavaScript.
lac32
You can define your own RESTful endpoints by adding custom endpoints. These handlers are free-form and do not need to map to a specific data model. You can implement functionality and return a JSON or HTML response using custom endpoints that include JavaScript.
You can:
  • Indicate that requests to your custom endpoint require authentication.
  • Run custom endpoints that return JSON or HTML format.
The following video demonstrates how to use 
CA Live API Creator
 to create and test a simple custom endpoint for your API 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 you do not see this option, clear the
    Short Menu
    checkbox that appears below the menus.
  2. Click
    Add
    .
    A new custom endpoint displays on the Custom Endpoints page. The following images shows this page:
      CA Technologies
  3. Complete the fields on the page, and then click
    Save
    :
URL pattern
The regular expression that is matched with the incoming request's URL to call this custom endpoint. This expression must follow the conventions of Java regular expressions. If more than one custom endpoint matches a request's URL, 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 endpoints is created and is active.
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 issues calls such as
    resourceGet
    .
     To use 
    resourceGet
    , your custom endpoint must indicate that requests to the endpoint require a client authentication token.
For more information about the
logicContext
object, see The logicContext Object.
Run Custom Endpoints
You can run custom endpoints:
Run Custom Endpoints Returning JSON Format
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 
request
 object is a Java request object, or an instance of 
HttpServletRequest
, and is different than the request objects you get in other contexts, such as in rules and events. When writing a handler, you take control and API Creator does not create a standard request object.
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 based on your business rules and 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 Returning HTML Format
Custom endpoints can return HTML. For example, you can create simple HTML pages and return the content with the following code:
responseHeaders.put('Content-Type', 'text/html');
The Business to Business example defines the 
Menu
custom endpoint, as shown in the following image:
Run this custom endpoint by copying the contents of the URL to a new browser page, as shown in the following image:
CA Technologies
Run Custom Endpoints with URL-Encoded Payloads in POSTs
Define the 
formParameters
 variable only if the request is a POST and the payload is URL-encoded. In the header, set the 
Content-Type
 of the request to 
application/x-www-form-urlencoded
.
Pass the following parameters in the payload of a POST.
You can enumerate and get the parameter values using the 
formParameters
 variable, for example:
if (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);
        }
    }
}
Test your Custom Endpoint
Copy the contents of the URL to a new browser page.