/

Getting Started

Lingo4G offers the HTTP REST API to provide concurrent access to one or more projects (document indexes) over the network.

The API follows typical patterns found in many REST-based services:

  • HTTP protocol is used for sending and retrieving messages, including starting analyses, inspecting their progress and retrieving the results. Message exchanges using HTTP can be synchronous or asynchronous (depending on the endpoint) and make use of different HTTP request methods and response codes.

  • JSON is the data exchange format. All exchanged messages (requests and responses) must be encoded as UTF-8 JSON.

Lingo4G's REST API v2 is part of the built-in HTTP server, started using the server command. Once the server is started, it will display the URIs of API versions that are available, for example: 

> Lingo4G server started on port 8080 with the following services:
  Project 'example', 122,655 documents in the index.
    Static resources: http://localhost:8080/
    Lingo4G API V1: http://localhost:8080/api/v1
    Lingo4G API V2: http://localhost:8080/api/v2

This chapter describes API v2 only. API v1 is part of Lingo4G 1.x line, its documentation is provided with older product releases. API v1 exists in Lingo4G 2.0 and subsequent releases for backward compatibility only.

Once you select the API version, you can use the HTTP protocol to query the server status, start analytical requests, monitor their progress and eventually collect their results. A single server can provide access to one or more Lingo4G projects (document indexes).

Where to start?

These are a few key elements to identify before running a REST API request:

  • identify the functionality you need. Most often, you'll need to run an analysis request, but other endpoints provide server status, request schema and other information that goes beyond the core functionality of analytical requests.

  • Identify the API endpoint that fulfills your needs; for this endpoint, locate the URI suffix it uses, the HTTP method it accepts, and any potential input message or parameters it expects to receive.

  • Send the message to the server using the right HTTP protocol method (typically GET or POST), process the HTTP status response and parse the result message body (if any).

The REST API is designed so that it can be accessed from any language. For quick experiments, even a basic curl command should be sufficient to interact with the server. We provide examples of curl commands, along with full HTTP requests and responses in the documentation of each API endpoint.

Endpoints

An API endpoint is a HTTP service living under a suffix URL of the server's base services prefix. All endpoints in this documentation omit the base services prefix for brevity. Typically, API base is at host:​port/api so any API v2 endpoints would live under host:​port/api/v2/. Note that for multi-project servers, the API prefix may be different for each project.

The API v2 endpoints can be organized into the following groups, covering different functionality.

analytical engine project descriptor server status and index control