Working with Endpoints

Added in 24.06.

Endpoints supported in Aurora offer similar functionality as the Freemarker endpoints in Classic Studio.

Aurora endpoints are custom TypeScript functions that run as Express Middleware on the Aurora server (that runs on express.js) to serve HTTP requests to a specific URL. TypeScript is JavaScript with syntax for different types.

Since endpoints provide a way to connect with third-party APIs, they can be used to integrate with third-party frameworks. Aurora endpoints can also be used by external integrations to get your community data (this use case with GraphQL is not as common as it was with classic Freemarker Endpoints).

The Community Plugin Git repository is used to define custom endpoints.

Permissions

You must have access to your community Plugin Git repository to add an endpoint.

Note: To access your community Git Repository, Contact Khoros Support.

Lifecycle of an Endpoint

The lifecycle of an endpoint in your Aurora community comprises four stages:

1. Developing an endpoint
2. Building and deploying the endpoint
3. Installing the endpoints
4. Calling an endpoint

Developing an endpoint

You can develop an endpoint by adding the following files to the endpoint folder in your Git repository:

• An endpoint descriptor file (.endpoint.json) is used to generate the path to the endpoint. You can specify the HTTP methods that must be used to request the endpoint. If the HTTP method supports a request body, you can also add one. Learn more about the Endpoint Descriptor file.
• An endpoint module file (index.ts) written in TypeScript that serves as an entry point to the endpoint. This contains a function that the middleware will run when the endpoint is called. Learn more about the Endpoint Module file.
• A package file (package.json) to build and deploy the endpoint.

Adding the Files to the Git Repository

For example, using catFact as a naming convention, where the fact information from the cat fact URL is displayed in the endpoint URL. See cat Fact API for more information.

The endpoint URL after development is:

https://[COMMUNITY-DOMAIN]/endpoints/<endpoint-id>

The source for our example endpoint can be found in the aurora plugin example repository.

For our example, the endpoint URL is:

https://[COMMUNITY-DOMAIN]/endpoints/CatFact

Steps:

1. Sign in to your community’s Git repository.
2. Ensure your community’s Git repository has a src folder. If not, create it:

   mkdir src

3. Create an endpoints folder under src:

   mkdir endpoints

4. Create a CatFact folder under your endpoints folder.
5. Create a CatFact.endpoint.json file under your CatFact folder. Add the following content:

   {
     "id": "CatFact",
     "httpMethods": ["GET", "POST"],
     "bodyType": "NONE"
   }

6. Create an index.ts file under your CatFact folder. Example content:

   import type { EndpointHandlerContext } from 'aurora/externalServerContext';
   import type { RouteParameters } from 'express-serve-static-core';
   
   interface CatFactResponse {
     message: string;
   }
   
   const API = 'https://catfact.ninja/fact';
   
   async function handler(context: EndpointHandlerContext<RouteParameters<string>, CatFactResponse>) {
     const {
       client: { fetch },
       server: { request, response },
       utils: { log }
     } = context;
     log.info('Handling request at', request.originalUrl);
     const apiResponse = await fetch(API);
     if (apiResponse.ok) {
       const json = (await apiResponse.json()) as Record<string, unknown>;
       return response.json({
         message: `Cat fact: ${json.fact}`
       });
     } else {
       return response.status(apiResponse.status).send({ message: 'Error!' });
     }
   }
   
   export default handler;
   

7. Create a package.json file under your CatFact folder.
8. Commit and push these changes to a branch of your plugin in your community.
9. Call the endpoint on your working branch by passing the kh-branch-name header.
10. After the branch name is set in the kh-branch-name header, you should be able to call the endpoint on the branch you pushed it to.
11. Create a pull request to merge these changes into the main branch of your plugin (stage-main, not main). The pull request must be merged.

Endpoint Descriptor File

The endpoint descriptor file is written in JSON and contains the ID of the Endpoint that is used to generate the path. The naming convention for the endpoint descriptor file must have the same name as the endpoint directory followed by the .endpoint.json suffix. You can add the fields in the table below to your descriptor file.

Field Name	Mandatory	Description	Possible Values	Default Value	Example
id	Yes	ID of the endpoint used in the generation of the URL to your endpoint. The naming convention must be the same as the endpoint directory name.	Not Applicable	No default	"id":"catFact"
httpMethods	No	The HTTP methods used to request the endpoint.	"GET", "POST", "PUT", "PATCH", "DELETE"	["GET", "POST"]	"httpMethods": [ "POST", "PUT" ]
bodyType	No	Type of the request body to expect if the HTTP method supports a request body.	JSON, MULTIPART, MULTIPART_FILES, URL_ENCODED, NONE	JSON if httpMethod is POST, PUT, PATCH, or DELETE. NONE if httpMethod is GET.	"bodyType": "MULTIPART"
pathPrefix	No	A prefix to place after the /endpoints/ path element but before the id path element	Not Applicable	NO DEFAULT	"pathPrefix": "animals/animalname"
pathSuffix	No	A suffix to allow the endpoint to support URL parameters.	Not Applicable	NO DEFAULT	"pathSuffix": "/animals/:name"

Endpoint Module File

The endpoint module file must be named index.ts. It should implement the EndpointHandler interface packaged with the Aurora SDK by returning a function defined in the interface.

The handler function takes a single argument called context and implements the EndpointHandlerContext interface to your endpoint.

export interface EndpointHandler<
  P = ParamsDictionary,
  ResponseBody = unknown,
  RequestBody = unknown,
  RequestQuery = ParsedQs
> {
  (
    context: EndpointHandlerContext<P, ResponseBody, RequestBody, RequestQuery>
  ): Promise<void> | void;
}

The context argument provides access to:

• server: EndpointServerContext (request, response, caller, tenant, pathContext)
• client: EndpointClientContext (fetch, graphql, graphqlAdmin)
• utils: EndpointUtilsContext (log)

See the documentation above for detailed field descriptions.

Allowed Domains

Certain endpoints make calls to third-party APIs to retrieve data. To add these third-party API URLs, go to Account > Dev Tools > Endpoint Settings and add your URLs to the Allowed Domain for Endpoints field. Valid domains must be in the format .domain.com (preceded by a dot).

Package JSON file

The package.json file is used to build and deploy the endpoint and install dependencies. It also contains information about the middleware.

Starting in 25.01, any dependencies in an endpoint's package.json file that are not in the allowlist will fail the Github Actions Build (or fail locally when you run npm run build) and prevent the endpoint from being installed.

Allowlisted dependencies:

• brotli
• clone-deep
• cookie
• dateformat
• js-base64
• jsonwebtoken
• lil-uri