Important
This feature is in LABS and is subject to change.
A custom endpoint combines business logic and calls to Rosette endpoints into a new endpoint that is fully integrated in Rosette Server. With a single call, you can make calls to multiple Rosette endpoints, follow specific workflows, and execute custom logic.
The custom endpoint architecture includes two platform-independent components:
A reverse proxy that is placed in front of the normal entry point. The shipment includes a Spring Boot application that utilizes Zuul, an open source routing framework, in order to provide a reverse proxy capability.
An application server to host the endpoint code. The shipment includes Tomcat, an open source Java application.
Note
Zuul and Tomcat are provided as an example of one way to implement a custom endpoint. You can substitute your preferred reverse proxy or application server to achieve the same results.
The reverse proxy's configuration file routes all incoming requests:
Calls to standard Rosette endpoints are routed to the Rosette server as usual.
Calls to custom endpoints are routed to the application server, which makes calls to standard Rosette endpoints and applies custom logic.
All shipments contain the file rosent-custom-endpoint-installer-<version>.tar.gz
containing an installation script and the files for the reverse proxy and application server. The installation script is currently for Linux and macOS only.
You can install the custom endpoints while Rosette Server is running, or start it after you complete the custom endpoints installation.
Install Rosette Server as usual. Ensure JAVA_HOME
is set.
Download and extract rosent-custom-endpoint-installer-<version>.tar.gz
from your shipment email. The files will be extracted into a directory named rosent-custom-endpoint-installer-<version>
.
-
Run rosette-custom-endpoint-installer.sh
.
./rosette-custom-endpoint-installer.sh
-
The file services_startup.conf
can report the status of the proxy and application servers when Rosette launches. To use this feature, the file must be placed in the /conf
directory of your Rosette installation.
The install will prompt you for the location of the file. If the suggested default location is not the /conf
directory of your Rosette installation, enter the correct location when prompted. Example:
Would you like to configure a services_startup.conf file during this install? [Y/N] (default: Y) ->
Enter the directory to store the services_startup.conf (default: /Users/userid/conf)1 ->
/Users/userid/rosette/server/conf 2
Is this correct? /Users/userid/rosette/server/conf [Y/N] (default: Y) ->
1 |
Default location |
2 |
Location of Rosette installation entered during installation |
-
You will be prompted for the <reverse_proxy_install_directory
.
Enter the desired Rosette Enterprise Proxy installation directory (default: /Users/userid/proxy) ->
Is this correct? /Users/userid/proxy [Y/N] (default: Y) ->
This step creates a new directory /Users/userid/proxy/rosent-proxy-<version>/
. You will need this directory when Configuring a Custom Endpoint.
[INFO] /Users/userid/proxy does not exist, creating.
[INFO] Updating /Users/userid/proxy/rosent-proxy-0.0.8/conf/proxy-wrapper.conf to have absolute paths
to application.yml and logback.xml
-
Edit the file services_startup.conf
in the <Rosette_installation>/server/conf>
directory:
Uncomment the lines CUSTOM_ENDPOINT_HEALTHCHECK_URI
and PROXY_HEALTHCHECK_URI
.
Verify the URIs - if you changed the URIs during installation, update the values. If you accepted the default values, no change is required.
CUSTOM_ENDPOINT_HEALTHCHECK_URI=http://localhost:8183
PROXY_HEALTHCHECK_URI=http://localhost:8182/actuator/info
Configuring and Running the Services
(Optional) Modify the <tomcat_install_directory>/properties/config.properties
file If non-default ports or other changes to the defaults were specified during installation. You can also modify rosette_url
to bypass the reverse proxy and point directly to the traditional endpoint of Rosette.
-
Start the application server: tomcat/apache-tomcat-<version>/bin/rosent-tomcat.sh start
-
To start the service:
tomcat/apache-tomcat-<version>/bin/rosent-tomcat.sh start
The following messages are displayed when the application server starts up:
Starting RosetteEnterprise Tomcat...
Waiting for RosetteEnterprise Tomcat......
running: PID:76987
-
To stop the service:
tomcat/apache-tomcat-<version>/bin/rosent-tomcat.sh stop
-
To get the status of the service:
tomcat/apache-tomcat-<version>/bin/rosent-tomcat.sh status
-
To view the console logs:
tomcat/apache-tomcat-<version>/bin/rosent-tomcat.sh console
-
Start the proxy server: proxy/rosent-proxy-<version>/bin/rosent-proxy.sh start
-
To start the service:
proxy/rosent-proxy-<version>/bin/rosent-proxy.sh start
The following messages are displayed when the proxy server starts up:
Starting RosetteEnterprise Proxy...
Waiting for RosetteEnterprise Proxy......
running: PID:77560
-
To stop the service:
proxy/rosent-proxy-<version>/bin/rosent-proxy.sh stop
-
To get the status of the service:
proxy/rosent-proxy-<version>/bin/rosent-proxy.sh status
-
To view the console logs:
proxy/rosent-proxy-<version>/bin/rosent-proxy.sh console
Start Rosette Server
Configuring a Custom Endpoint
The reverse proxy installer comes with a default configuration file for forwarding standard Rosette endpoint calls to the installation on localhost. It also comes with a templated routing section for custom calls that is updated by the install script.
The file is: <reverse_proxy_install_directory>/application.yml
where the reverse_proxy_install_directory
was set when Installing.
Add or modify the existing rules by editing the settings block zuul:
For example, to add a new rule to update the proxy to correctly route calls to a custom application at http://localhost:8182/rest/custom/mycode
, add the mycode under the zuul:
section:
zuul:
routes:
mycode:
path: /rest/mycode/**
url: http://localhost:8181/rest/custom/mycode
If your custom code is in Java, put your WAR file into the webapps
directory of the Tomcat installation directory. To use other languages, see Adding Non-Java Custom Code.
Your Java web application should define a URI to access the code. Create a rule in the proxy definition to adjust the final path to access the custom code.
Each component, including Rosette Server, has its own, independent, Tanuki Java Wrapper application. Tanuki monitors the health of the application and relaunches if the Java application crashes or gets into a bad state.
In addition, the proxy application exposes two endpoints that can be used to access the proxy health:
-
/actuator/info
: Returns a version of the running proxy and a short description. Example:
curl http://localhost:8182/actuator/info
Returns:
{
"app": {
"name": "ROSEnt Proxy",
"version": "0.0.1",
"description": "Used to route custom ROSEnt API Requests"
}
}
-
/actuator/health
: Indicates if the proxy is UP or Down. Example:
curl http://localhost:8182/actuator/healthy
Returns:
{
"status": "UP"
}
Note
Access to these endpoints can be restricted to network interface if required. Details on restricting access can be obtained from Basis support or Spring Boot Actuator documentation, by setting the management server address and port.
Note
The source code for the example application is located in the installer as custom-application-sources.jar
. You do not need to extract the file to run the example application as there is a compiled and packaged version of the code deployed with the Tomcat application server. You only need to access the source code if you want to use it as a template for your own endpoint.
The custom endpoint application includes an example application, matchSentences , which calculates the relevance of documents and sentences against a list of keywords. It combines calls to the /sentences
and /semantics/vector
endpoints with custom code. The custom code uses the cosine similarity function to calculate similarity scores between the sentences and the keywords, as well as comparing the scores to the input threshold value.
The input is a list of keywords, a document or the URL to a document, and a threshold.
The response is the cosine similarity scores and a true/false value indicating if the score is above the threshold for each sentence, and for the entire document.
Example payload
File: matchSentences.json
{
"keywords": [
"USA",
"Iran",
"attack",
"protest"
],
"document": "Iran was planning attacks on four US embassies
when its top general was killed, President Donald Trump says.
When asked what threat led to last Friday's US drone strike,
he told Fox News: \"I can reveal that I believe it probably
would've been four embassies.\" \"The killing of Gen Qasem Soleimani,
a national hero, came after days of protests at the US embassy in Baghdad.",
"threshold": 0.25
}
Call /matchSentences
curl -s http://localhost:8182/rest/custom/matchSentences -XPOST \
-H 'Content-Type: application/json; charset=utf-8' -d \
@matchSentences.json
How does the call know where to find the Rosette endpoints?
Look at the <reverse_proxy_install_directory>/application.yml
file. The zuul
section defines the redirects.
zuul:
routes:
custom:
path: /rest/custom/**
url: http://localhost:8183/custom-application/custom-app/services
Wherever zuul sees the path /rest/custom/
it replaces it with the url listed in the application file. The curl command calls http://localhost:8182/rest/custom/matchSentences
. It gets routed to http://localhost:8183/custom-application/custom-app/services/matchSentences
.