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:

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:

Add Custom Endpoints

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.

Click Add
.

A new custom endpoint displays on the Custom Endpoints page. The following images shows this page:

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:

That return JSON.

That return HTML format.

With URL-encoded payload in a POST.

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

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:

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.

Extensibility

CA Live API Creator 3.2

Custom Endpoints