Querying
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:
Param | Description |
---|---|
url | The url the query is exposed under. It must start /api/q . Any other query URLs are ignored |
method | The 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)
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