Articles in this section

See more

Custom Endpoints

Avatar
Jason Stevens
  • Updated
Follow

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.

Architecture

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 Spring Cloud Gateway, an open source routing framework, in order to provide a reverse proxy capability.

  • The custom endpoint is a Spring Boot application and can either be deployed as a web archive (WAR) using Tomcat or as a stand-alone Spring Boot application.

Note

Spring Cloud Gateway 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.

Installing

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.

  1. Install Rosette Server as usual. Ensure JAVA_HOME is set.

  2. 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>.

  3. Run rosent-custom-endpoint-installer.sh.

    ./rosent-custom-endpoint-installer.sh

  4. The installer will guide you through the installation and customization process.

    1. You will have the option of installing tomcat to host the custom endpoints.

    2. You will have the option to install the stand-alone sample and source code.

    3. The sample can be deployed as a standalone Spring Boot application or as a ware deployed in tomcat.

Configuring and Running the Services

  1. 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

  2. Start the proxy server: proxy/bin/rosent-proxy.sh start

    • To start the service:

      proxy/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/bin/rosent-proxy.sh stop

    • To get the status of the service:

      proxy/bin/rosent-proxy.sh status

    • To view the console logs:

      proxy/bin/rosent-proxy.sh console

  3. Start Rosette Server

Configuring a Custom Endpoint

The application.yml file configures most aspects of the proxy including ports, certificates, routing, and timeouts. If you move the application.yml file, the ./conf/proxy-wrapper.conf must be updated with the new location.

wrapper.app.parameter.2=--spring.config.location=<new file location>

The proxy can be configured using the values in the application.yml file directly or by setting the environment variables in ./conf/proxy-wrapper.conf. 

  • To set the port the proxy will use: s

    set.PROXY_PORT=8182

  • To set the location logs are written to: set.PROXY_LOG_DIR=./logs 

    set.PROXY_LOG_DIR=./logs

  • To set the location of the custom application: set.SAMPLE_ENDPOINT_APP_HOST=http:/localhost:8183 

    SAMPLE_ENDPOINT_APP_HOST=http:/localhost:8183

  • The location of Rosette Server:

    set.ROSETTE_SERVER_HOST=http://localhost:8181

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.

Resiliency

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:

  • /info: Returns a version of the running proxy and a short description. Example:

    curl http://localhost:8182/info

    Returns:

    {
  "app": {
    "name": "rosent-proxy",
    "description": "Rosette Custom Endpoint Proxy",
    "version": "0.3.0",
  }
}

  • /health: Indicates if the proxy is UP or Down. Example:

    curl http://localhost:8182/health

    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.

Example

Note

The source code for the example application is located in the directory /rosette/custom-endpoint. 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.

Call the Endpoint

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/v1/match-sentences -XPOST \
-H 'Content-Type: application/json; charset=utf-8' -d \
@matchSentences.json

Example Configuration

Spring Cloud Gateway is used for proxy routing. There are 2 routes defined by /rest/v1/match-sentences and /rest/v1/**. All traffic sent to /rest/v1/match-sentences will be sent to the custom application.

The custom application will change depending on how the application is being run.

  • When run as a Spring Boot application the path is /rest/v1/match-sentences -> /service/matchSentences 

  • When deployed as a war the path is /rest/v1/match-sentences -> /custom-endpoint/matchSentences.

  • The paths to /info endpoints is either /service/info or /custom-endpoint/info.

spring:
  cloud:
    gateway:
      routes:
        # Route to the custom endpoint
        - id: sample_app_route
          uri: ${SAMPLE_ENDPOINT_APP_HOST:http://localhost:8183}
          predicates:
            - Path=/rest/v1/match-sentences/**,matchTrailingSlash=false
          filters:
# When running the custom endpoint as a stand-alone spring boot application
#           - RewritePath=/rest/v1/match-sentences/info(?<segment>.*), /service/info$\{segment}
#           - RewritePath=/rest/v1/match-sentences/health(?<segment>.*), /service/health$\{segment}
#           - RewritePath=/rest/v1/match-sentences/prometheus(?<segment>.*), /service/prometheus$\{segment}
#           - RewritePath=/rest/v1/match-sentences/env(?<segment>.*), /service/env$\{segment}
#           - RewritePath=/rest/v1/match-sentences(?<segment>.*), /service/matchSentences/$\{segment}
# When running the custom endpoint as a war file in tomcat
#           - RewritePath=/rest/v1/match-sentences/info(?<segment>.*), /custom-endpoint/info$\{segment}
#           - RewritePath=/rest/v1/match-sentences/health(?<segment>.*), /custom-endpoint/health$\{segment}
#           - RewritePath=/rest/v1/match-sentences/prometheus(?<segment>.*), /custom-endpoint/prometheus$\{segment}
#           - RewritePath=/rest/v1/match-sentences/env(?<segment>.*), /custom-endpoint/env$\{segment}
#           - RewritePath=/rest/v1/match-sentences(?<segment>.*), /custom-endpoint/matchSentences/$\{segment}
     # Calls to Rosette Server Endpoints
     - id: rosette_pass_thru
       uri: ${ROSETTE_SERVER_HOST:http://localhost:8181}
       predicates:
         - Path=/rest/v1/**,matchTrailingSlash=false
         - Path=/rest/**,matchTrailingSlash=false

Adding Non-Java Custom Code

The examples and instructions here assume you are writing your custom code in Java. If you are using a different language, you will need to set up your own application server that is specific for that language. Then you add your own routing rules to the proxy so that the traffic is directed to the correct place.

Let's assume you'd like to add a python file named python_example.py,and you want to execute it from the url http://localhost:8182/rest/v1/python_example.

  1. Stand up a python application server.

  2. Configure the application server to work with the python_example.py file.

  3. Create a rule in the proxy's application.yml file that routes requests to rest/v1/python_example to the python application server such that it calls the python_example.py file.

Related articles

Comments

0 comments

Article is closed for comments.





Powered by Zendesk