Learning Record learning from practice

OpenGrok REST API: Search, Raw Files, and Authentication

#opengrok

OpenGrok exposes a REST API below /api/v1/. The exact deployment URL depends on the servlet application’s context name, so the examples below use <opengrok-base-url>.

The most useful distinction is between searching source code and managing the OpenGrok web application. These operations do not necessarily have the same authentication requirements.

Endpoint permissions

OpenGrok documents three relevant permission behaviors:

Operation Typical endpoint Authentication behavior
Health and monitoring /api/v1/system/ping, /api/v1/system/indextime, /metrics Public; no bearer token required
Source browsing and search /api/v1/search, /api/v1/file/..., /api/v1/history/..., /api/v1/annotation/... Controlled by the authorization framework when it is configured
Administration and configuration /api/v1/projects, /api/v1/configuration, and other management operations Requires an API bearer token for protected access

The API documentation also notes that /metrics is outside the /api/v1 prefix. Do not assume that a successful search request proves that every API endpoint is available to the same client.

Reading source files

The /raw route is useful when a client needs the original file content rather than an HTML page. A generic request looks like this:

curl -L "<opengrok-base-url>/raw/<project>/<file>"

Use the API’s file-content endpoint when you need content negotiation. For example, a client can request plain text with an Accept: text/plain header:

curl -H "Accept: text/plain" \
  "<opengrok-base-url>/api/v1/file/<project>/<file>"

The raw route and the API route serve different purposes. A raw URL is not a directory browser; use the directory-listing or search API when you need to discover files.

Searching definitions and references

The search endpoint accepts separate fields for different kinds of queries:

Purpose Parameter Example value
Full-text search full ERROR
Definition search def init_config
Symbol/reference search refs init_config
File-path filter path <project>/*.c
History search hist fix initialization

For example, these requests search definitions and references without exposing any repository-specific names:

curl -G "<opengrok-base-url>/api/v1/search" \
  --data-urlencode "def=my_function"

curl -G "<opengrok-base-url>/api/v1/search" \
  --data-urlencode "refs=my_symbol" \
  --data-urlencode "path=<project>/"

The same search concepts can be expressed through the q query syntax, such as defs:my_function and refs:my_symbol. Query parameters are easier to compose from scripts because curl --data-urlencode handles escaping.

Search fields can be combined. This example limits a reference search to a project subtree and also requires a text match:

curl -G "<opengrok-base-url>/api/v1/search" \
  --data-urlencode "refs=init_config" \
  --data-urlencode "path=<project>/src/" \
  --data-urlencode "full=ERROR" \
  --data-urlencode "maxresults=20"

Treat path patterns as OpenGrok query syntax rather than assuming that shell, Git, and OpenGrok interpret recursive wildcards identically. Start with a literal project or directory filter, verify the result, and then add a pattern if the deployment’s OpenGrok version supports the form you need.

Calling protected endpoints

Configure one or more API tokens in the web application’s configuration, then send a token in the Authorization header:

<void property="authenticationTokens">
    <void method="add">
     <string>REPLACE_WITH_A_SECRET_TOKEN</string>
    </void>
</void>

curl -H "Authorization: Bearer REPLACE_WITH_A_SECRET_TOKEN" \
  "<opengrok-base-url>/api/v1/projects"

Use HTTPS for requests that carry tokens. OpenGrok can be configured to accept tokens over plain HTTP with allowInsecureTokens, but the official setup guide describes that as a setting for trusted internal communication. It should not be enabled casually for a network-facing deployment.

After changing the web application configuration, make sure the running application has loaded the new configuration. When an indexer updates a remote web application, configure its token with the indexer’s token option or its read-only configuration, as appropriate for the deployment.

Why a request returns 401

An HTTP 401 response is often a sign that the request crossed an API permission boundary rather than that the URL is malformed. Check the following in order:

  1. Confirm that the request uses the deployed application base URL.
  2. Test a public health endpoint to confirm that the web application is alive.
  3. Determine whether the target endpoint is protected administration API.
  4. Send Authorization: Bearer <token> and verify that the token is configured in the web application.
  5. If the request uses HTTP, check whether allowInsecureTokens is explicitly enabled; HTTPS is the preferred fix.

OpenGrok also distinguishes API authorization from user authentication and source authorization. A web server’s login mechanism, an authorization plugin, and an API bearer token solve different problems and should be configured independently.

References