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:

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)

​

OpenAPI

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