Developing APIs‎ > ‎Extensibility‎ > ‎

Custom Endpoints

Define your own RESTful endpoints by creating custom endpoints. These handlers are free-form and do not need to map to a specific data model. The JavaScript can implement any functionality and return a JSON response.

With custom endpoints, you can:

  • Indicate that requests to your custom endpoint require authentication.
  • Return JSON and other formats, such as HTML.
Note: Custom endpoints do not enforce security.

Create Custom Endpoints

  1. With your API open, go to Create, Custom Endpoints.
  2. Click Add.
  3. Enter a name for your custom endpoint in the Custom endpoint name field and then save your changes.
The custom endpoints is created and is active.

Custom Endpoints that Require an Authentication Token

By default, a client authentication token is not required to use custom endpoints. You can indicate that requests to your custom endpoint require a client authentication token by selecting the Authenticate checkbox on the Create, Custom Endpoints page. the following images shows this checkbox on this page:

You can extend an endpoint to use more complex authentication measures using the logicContext object.

Note: For non-authenticated requests:

  • The logicContext object is null.
  • You cannot issues calls such as resourceGet.
    Note: To use resourceGet, you must indicate that requests to your custom 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 or HTML format.

Run Custom Endpoints Returning JSON Format

Your custom endpoint is called 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 include custom response codes and their descriptions as part of your JSON response. 

For more information about the request object, see The Request Object.

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:

Test your Custom Endpoint

Copy the contents of the URL to a new browser page.

Deactivate Custom Endpoints

By default, the custom endpoints you create are active. You can deactivate your custom endpoint by clear the Active checkbox on the Create, Custom Endpoints page.