Endpoints provide you a way to expose your own custom business logic on top of your Curiosity application, with direct access to the underlying graph database, NLP models and other functionality. Custom Endpoints are written in C# from within your browser, and can be made accessible to logged users of your site, embedded in your views (for example to return customizable HTML), or in your own custom front-end built using the custom front-end components.

To get started, open the Manage Endpoints link in your administrator landing page:

You'll see then a list of existing endpoints. From there you can create and delete existing endpoints, check for issues and exceptions, and edit the code behind them.

Creating an Endpoint

To create a new endpoint, click on New Endpoint. The endpoint editor will show:

You can write your endpoint logic using the Code area. The response of your endpoint will be given by the value you return from your code (the example above always returns the string "hello word").

There are a few options for you to configure as well:

  • Endpoint name: This defines the name (and thus the path) of your final endpoint. You can use slashes ('/') to create hierarchy of endpoints (this can be useful for accessing endpoints directly using custom Endpoint Tokens, which can be scoped to a given endpoint name or path)

  • Cache Duration: Specifies if the application should cache the result of the computation, and for how long. Set to zero to always run the endpoint code on every call. Caching can be useful for endpoints that perform expensive computations and might be called often by your end-users or external APIs - an example could be an endpoint providing daily aggregates or analytics that have to iterate through a large amount of data.

  • Access Control: When being called from within the front-end, endpoints can be restricted to either all logged users, or to only admin users.

  • API style: Curiosity provides two APIs to write your own endpoints - a stable and supported API (i.e. the simplified API in this dropdown), that is very similar to the API exposed by the external Library for writing connectors. This is the recommended API model to be used. Alternatively, expert users can use the Advanced API - that provides direct access to lower level APIs. These APIs must be used with care, and are not stable across versions - so you can expect things to change when you update your instance, requiring some rework on your endpoints. They are usually left for more advanced scenarios requiring high performance access to the graph data, fine grain control on changes, or access to other parts of the application not yet exposed in the simple API.

Once you're done writing your endpoint code (you can also use the Shell to prototype your endpoint), click on Create to deploy it on your application.

Editing Endpoints

You can click on any endpoint to open the editor.

On the top of the editor, you can see the different ways this endpoint can be called:

  • From the Front-End:

var response = await API.Endpoints.CallAsync<string>("hello");

  • Using a POST request (and an example using CURL):

POST to: http://localhost:5001/api/cce/token/run/hello

curl -X POST -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Bearer ${TOKEN}" --data "${BODY}" http://localhost:5001/api/cce/token/run/hello

See below how to create a token to call the endpoint directly (via POST or curl)

You can also test your endpoint: the editor provides a second area where you can define the Body content of your request (for example a JSON object). Click on Test to call the endpoint with the Body specified (if any). The response from the endpoint will be shown in the Test Output area.

Creating Endpoint API Tokens

You can create tokens to call your endpoints from outside your front-end (for example using CURL or Postman for testing). Click on the Manage Tokens button on the upper right corner of the interface:

You'll be taken to the Tokens settings page:

Click on New Token and Code Endpoints:

You need to give a description to your token, and the path or partial path of the endpoint you want to call.

For example, to call a single endpoint called hello:

To call a family of endpoints, you can also specify partial paths. For example, assuming you have a set of endpoints:

  • analytics/get-data

  • analytics/get-timeline

  • analytics/get-summary-for-year

You can create a token with the endpoint path "analytics/" to match any of the above endpoints:

Click on Save to create the token, and don't forget to copy the value to a safe place. You will not be able to see this token again once you close this dialog.

When calling your endpoint from outside using a POST request, you need to pass this token in the Authorization Header as a Bearer token.

For example, when calling using Postman, configure the request as follows:

Did this answer your question?