Exposing queries as HTTP Endpoints

You might decide that instead of submitting queries directly to Orbital, or using one of our SDKs to execute a query programmatically, that you’d rather just publish the query as an HTTP(s) endpoint.

Saved queries

Any queries committed to your taxonomy that have an @HttpOperation annotation will automatically be converted into a HTTP query.

For example:

@HttpOperation(url = '/api/q/movies/{movieId}', method = 'GET')
query getMoviesAndReivews(@PathVariable("movieId") movieId: MovieId) {
  given { movieId }
  find {
    title : MovieTitle
    reviewScore : ReviewScore

Any declared query that’s in a Taxi project published to Orbital can be converted into an HTTP Operation.

HttpOperation annotation

Queries need to have an @HttpOperation annotation:

urlThe url the query is exposed under. It must start /api/q. Any other query URLs are ignored
methodThe HTTP method to respond to, one of GET,POST,PUT, or DELETE

Variables can be defined in your path using {myVar}, which are then made available in your query declaration using a @PathVariable annotation.

Declaring the query

Named queries are defined using a query syntax:

Path Variables

// Declares a query named getMoviesAndReviews`
query getMoviesAndReviews(
   // Define variables to be passed in
   @PathVariable("movieId") movieId: MovieId
) { ... }

Request Body

For a POST query, the request body is also available:

query doASearch(@RequestBody searchRequest: SearchRequest) {

Given clause

If you’ve written Taxi queries before, you’re used to using the given clause to provide data into the query.

For saved queries, that data is often passed as a variable, so the syntax is slightly different:

// Not a saved query, given clause has a value:
given { movieId: MovieId = 123 }
find { ... }

// A saved query, the movieId comes from the params:
query findMoviesAndReviews(@PathVariable(...) movieId: MovieId) {
  given { movieId } // exposes the parameter into the query as a fact.
  find { ... }

Live Reload

Any changes made to the queries are automatically deployed.

  • When developing locally, this is as soon as you save a file.
  • In production, when using a Git repository, as soon as changes are merged, they’re deployed on the next poll (typically a couple of minutes)


Orbital automatically creates an OpenAPI spec for any query endpoints it serves.

The OpenAPI specs are available at /api/q/meta/{nameOfQuery}/oas.

For example, a query defined as query findMoviesAndReviews(...) would have an OpenAPI spec available at /api/q/meta/findMoviesAndReviews/oas

Using the Kotlin SDK