Orbital

https://orbitalhq.com/docs
Admin
Orbital is a data gateway that automates the integration, transformation, and discovery of data from...
Tokens:101,789
Snippets:723
Trust Score:7.1
Update:11 months ago
Show doc for...
Tokens:
Raw
### Start Local Orbital Instance with Docker Compose

Source: https://orbitalhq.com/docs/guides/apis-databases-kafka

This command sets up a local Orbital instance along with demo projects. It requires Docker and Docker Compose to be installed. It creates a directory, downloads a docker-compose.yml file, and starts the services in detached mode.

```bash
mkdir orbital-films-demo
wget https://github.com/orbitalapi/demos/raw/main/importing-through-ui/docker-compose.yml
docker compose up -d
```

--------------------------------

### Run Orbital Query via CURL API

Source: https://orbitalhq.com/docs/guides/apis-databases-kafka

This snippet demonstrates how to execute an Orbital query using the `curl` command-line tool. It shows an example of interacting with the Orbital API programmatically, which is an alternative to using the UI for query execution.

```bash
curl -X POST \
  http://localhost:9022/api/v1/query \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "find { Film[] } as { film: { name: Title id : FilmId description: Description } productionDetails: { released: ReleaseYear } providers: StreamingProvider }[]"
}'
```

--------------------------------

### Orbital Project Configuration (taxi.conf)

Source: https://orbitalhq.com/docs/workspace/projects

Example `taxi.conf` file demonstrating how to specify source roots and additional OpenAPI and Avro sources for an Orbital project. This configuration guides Orbital on where to find different types of API specification files.

```toml
name: com.example/my-taxi-project
version: 0.2.0
sourceRoot: src/
additionalSources: {
     "@orbital/config" : "config/*.conf",
     "@orbital/openapi" : "openapi/*.yaml"
     "@orbital/avro" : "avro/*.avsc"
}
```

--------------------------------

### Install Taxi CLI with SDKMan

Source: https://orbitalhq.com/docs/guides/installing

Installs the Taxi CLI using the SDKMan tool. This is a prerequisite for managing Taxi projects and launching Orbital. Ensure Docker and SDKMan are installed beforehand.

```shell
$ sdk install taxi

Downloading: taxi 1.42.0

In progress...

Installing: taxi 1.42.0
Done installing!

Setting taxi 1.42.0 as default.

```

--------------------------------

### Verify Taxi Installation

Source: https://orbitalhq.com/docs/guides/installing

Verifies that the Taxi CLI has been installed correctly by running the `taxi` command. This should display the installed version and usage information.

```shell
$ taxi

Taxi 1.42.0 @7ebfab5 
Usage: taxi [options] [command] [command options] Main options

```

--------------------------------

### Kitchen Sink Configuration Example

Source: https://orbitalhq.com/docs/workspace/overview

A comprehensive example demonstrating both file-based and Git-based project configurations within OrbitalHQ. It shows settings for file change detection, polling frequencies, and Git repository details.

```hocon
file {
   changeDetectionMethod=WATCH
   incrementVersionOnChange=false
   projects=[
      {
        isEditable=true
        path="/opt/var/orbital/schemas/taxi"
      }
   ]
   pollFrequency=PT5S
   recompilationFrequencyMillis=PT3S
}
git {
   checkoutRoot="/my/git/root"
   pollFrequency=PT30S
   repositories=[
      {
         branch=master
         name=my-git-project
         uri="https://github.com/something.git"
      }
   ]
}
```

--------------------------------

### Install Orbital Helm Chart

Source: https://orbitalhq.com/docs/deploying/production-deployments

Instructions for adding the Orbital Helm repository and upgrading or installing the Orbital chart on Kubernetes. This assumes Helm is installed and configured.

```shell
helm repo add orbital https://orbitalapi.github.io/helm
helm repo update

helm upgrade -i orbital orbital/orbital --namespace=orbital --create-namespace
```

--------------------------------

### Protobuf Example with Taxi Extension

Source: https://orbitalhq.com/docs/background/intro-to-semantic-integration

An example showcasing how to enrich Protobuf message fields with semantic metadata using Taxi extensions for data types.

```APIDOC
## Protobuf Message Definition

### Description
Defines a `Person` message with fields `name`, `id`, and `email`, where each field is semantically typed using Taxi extensions.

### Method
N/A (Schema definition)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

#### Success Response (N/A)
N/A

#### Response Example
```protobuf
syntax = "proto3";
import "taxilang/dataType.proto"; // Import the DataType extension
package tutorial;


message Person {
  string name = 1 [(dataType='PersonName')];
  int32 id = 2  [(dataType='PersonId')];
  string email = 3 [(dataType='PersonEmail')];
}
```
```

--------------------------------

### Install Taxi using SDKMan (Shell)

Source: https://orbitalhq.com/docs/guides/working-with-xml

This command installs the Taxi command-line tool using SDKMan, a package manager for managing multiple versions of SDKs. It's a prerequisite for initializing a new Orbital project.

```Shell
sdk install taxi
```

--------------------------------

### OpenAPI Example with Taxi Extension

Source: https://orbitalhq.com/docs/background/intro-to-semantic-integration

An example demonstrating how to use Taxi extensions within an OpenAPI specification to add semantic metadata to query parameters.

```APIDOC
## GET /pets

### Description
Returns all pets from the system that the user has access to. This endpoint allows filtering pets by tags, enhancing the query with semantic metadata.

### Method
GET

### Endpoint
/pets

### Parameters
#### Query Parameters
- **tags** (array[string]) - Optional - tags to filter by. This field is semantically typed as `petstore.Tag` using a Taxi extension.

### Request Example
N/A (GET request with query parameters)

### Response
#### Success Response (200)
- **pets** (array) - A list of pets matching the query criteria.

#### Response Example
```json
{
  "pets": [
    {
      "id": 1,
      "name": "Buddy",
      "species": "Dog"
    },
    {
      "id": 2,
      "name": "Whiskers",
      "species": "Cat"
    }
  ]
}
```
```

--------------------------------

### Git Repository Authentication URL Example

Source: https://orbitalhq.com/docs/workspace/connecting-a-git-repo

This example demonstrates the format for a HTTPS Git repository URL that includes authentication credentials. It uses a username and a personal access token for secure access to the repository.

```plaintext
https://alexhamilton:glpat-dundadadadundundun@github.com/orbital/reynolds-pamphlet

```

--------------------------------

### Configure File Repository via HOCON - Orbital

Source: https://orbitalhq.com/docs/workspace/connecting-a-disk-repo

This snippet shows how to configure a file repository for Orbital projects using a HOCON file. It allows specifying project paths, editability, change detection methods, and frequencies for polling and recompilation. This configuration is essential for managing schema repositories directly from the file system.

```HOCON
file {
    projects=[
        {
            // Optional (defaults to false). Indicates if the project can receive edits through the UI
            isEditable=true
            // Path to the folder containing a taxi.conf file.
            path="/opt/var/orbital/schemas/taxi"
        }
    ]

    // Optional - WATCH or POLL
    changeDetectionMethod=WATCH

    // Optional - Should the version of the project be incremented when the local disk changes?
    // False is a safe setting here
    incrementVersionOnChange=false

    // Optional.  If polling, define the frequency.
    pollFrequency=PT5S

     // Optional.  Defines the frequency that updates trigger recompilation.
     // Useful if you're locally editing a schema, and don't want to trigger
     // lots of recompilation
    recompilationFrequencyMillis=PT3S
}

```

--------------------------------

### Navigate to Demo Project Directory

Source: https://orbitalhq.com/docs/guides/apis-databases-kafka

This command navigates the user into the 'demo' directory, which is where Orbital typically stores project files after importing schemas. This is a common shell command for project-specific operations.

```shell
cd demo/

```

--------------------------------

### Example Configuration for Executor Access Token (Client Secret Post)

Source: https://orbitalhq.com/docs/data-policies/data-policies

This example shows the configuration parameters required to obtain an Executor access token using the `client_secret_post` authentication method. It specifies the client ID, client secret, and token URL.

```properties
--vyne.security.openIdp.executorRoleClientId=TheSchuylerSisters
--vyne.security.openIdp.executorRoleClientSecret=AngelicaElizaAndPeggy
--vyne.security.openIdp.executorRoleTokenUrl=http://localhost:9000/oauth2/token
```

--------------------------------

### Kotlin Data Class and Controller Example

Source: https://orbitalhq.com/docs/guides/generating-kotlin-from-taxi

Example of Kotlin code demonstrating a data class and a Spring Boot controller that utilizes generated Taxi types like 'FilmId' and 'FilmReview'.

```kotlin
data class FilmReview(
    val score: ReviewScore,
    val review: ReviewText
)

@GetMapping("/films/{filmId}/review")
fun getFilmReview(
       @PathVariable("filmId") filmId: FilmId
    ): FilmReview {
    return FilmReview(
        score = Random.nextInt(1,5),
        review = listOf("Good","Bad","Meh").random()
    )
}
```

--------------------------------

### Connect Swagger API

Source: https://orbitalhq.com/docs/guides/apis-databases-kafka

Integrate a Swagger/OpenAPI definition of a REST API into Orbital HQ. This allows Orbital to interact with external services.

```APIDOC
## Connect Swagger API

### Description
Connect to a Swagger/OpenAPI definition to expose a REST API within Orbital. This enables Orbital to query data from the API.

### Method
POST

### Endpoint
/api/data-source-manager/add

### Parameters
#### Request Body
- **project** (string) - Required - The target project name.
- **type** (string) - Required - The type of schema to import, e.g., "Swagger / Open API".
- **swaggerSource** (string) - Required - The URL of the Swagger/OpenAPI definition.
- **defaultNamespace** (string) - Required - The default namespace for the imported API schema.
- **baseUrl** (string) - Optional - The base URL for the API.

### Request Example
```json
{
  "project": "demo",
  "type": "Swagger / Open API",
  "swaggerSource": "http://films-api/v3/api-docs",
  "defaultNamespace": "com.petflix.listings",
  "baseUrl": ""
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the API connection.
- **message** (string) - A message confirming the API schema import.

#### Response Example
```json
{
  "status": "success",
  "message": "Swagger API schema imported successfully."
}
```
```

--------------------------------

### Example Configuration (Client Secret Basic with Scope)

Source: https://orbitalhq.com/docs/data-policies/data-policies

This configuration example demonstrates how to obtain an Executor access token using `client_secret_basic` and specifying custom scopes. The scopes are sent as a URL-encoded parameter in the token request.

```properties
--vyne.security.openIdp.executorRoleClientId=TheSchuylerSisters
--vyne.security.openIdp.executorRoleClientSecret=AngelicaElizaAndPeggy
--vyne.security.openIdp.executorRoleTokenUrl=http://localhost:9000/oauth2/token
--vyne.security.openIdp.executorRoleAuthenticationType=ClientSecretBasic
--vyne.security.openIdp.executorRoleScopes=scope1 scope2 scope3
```

--------------------------------

### Import Database Schema

Source: https://orbitalhq.com/docs/guides/apis-databases-kafka

Configure and import a database table schema into Orbital HQ. This process generates models, types, and query services for the table's content.

```APIDOC
## Import Database Schema

### Description
Select a database table to import into Orbital. Orbital will create schema files, including a model for the table, types for field content, and a query service.

### Method
POST

### Endpoint
/api/import/schema

### Parameters
#### Request Body
- **connection** (string) - Required - The name of the database connection.
- **table** (string) - Required - The name of the table to import.
- **defaultNamespace** (string) - Required - The default namespace for generated schema files.

### Request Example
```json
{
  "connection": "films-database",
  "table": "film",
  "defaultNamespace": "com.petflix.films"
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the schema import.
- **message** (string) - A message confirming the schema creation.

#### Response Example
```json
{
  "status": "success",
  "message": "Schema configuration created successfully for table 'film'."
}
```
```

--------------------------------

### Test REST API using cURL and jq

Source: https://orbitalhq.com/docs/guides/working-with-xml

Provides an example command to test the published REST API using cURL to fetch the data and jq to format the JSON output for readability.

```bash
$ curl http://localhost:9022/api/q/filmsAndAwards | jq
```

--------------------------------

### Example Configuration for Executor Access Token (Client Secret Basic)

Source: https://orbitalhq.com/docs/data-policies/data-policies

This example configures Orbital HQ to obtain an Executor access token using the `client_secret_basic` authentication method. It includes client ID, client secret, token URL, and explicitly sets the authentication type.

```properties
--vyne.security.openIdp.executorRoleClientId=TheSchuylerSisters
--vyne.security.openIdp.executorRoleClientSecret=AngelicaElizaAndPeggy
--vyne.security.openIdp.executorRoleTokenUrl=http://localhost:9000/oauth2/token
--vyne.security.openIdp.executorRoleAuthenticationType=ClientSecretBasic
```

--------------------------------

### Define Operation Contracts and Constraints

Source: https://orbitalhq.com/docs/describing-data-sources/http

Shows how to define contracts and constraints for operations, providing metadata about functionality and invocation conditions. Includes an example of deriving a return type from an input parameter.

```Taxi
type Money {
   currency : String
   amount : Decimal
}
operation convertCurrency(input: Money,
      targetCurrency: String) : Money(from input, currency = targetCurrency)
```

--------------------------------

### OpenAPI Example with Taxi Semantic Metadata Extension

Source: https://orbitalhq.com/docs/background/intro-to-semantic-integration

This snippet demonstrates how to extend an OpenAPI definition to include semantic metadata using the 'x-taxi-type' extension. This allows consumers to define their data shape while abstracting producer-specific field names. The example shows how to annotate a 'petstore.Tag' semantic type within the OpenAPI paths.

```yaml
paths:
  /pets:
    get:
      description: |
        Returns all pets from the system that the user has access to
        Nam sed condimentum est. Maecenas tempor sagittis sapien, nec rhoncus sem sagittis sit amet. Aenean at gravida augue, ac iaculis sem. Curabitur odio lorem, ornare eget elementum nec, cursus id lectus. Duis mi turpis, pulvinar ac eros ac, tincidunt varius justo. In hac habitasse platea dictumst. Integer at adipiscing ante, a sagittis ligula. Aenean pharetra tempor ante molestie imperdiet. Vivamus id aliquam diam. Cras quis velit non tortor eleifend sagittis. Praesent at enim pharetra urna volutpat venenatis eget eget mauris. In eleifend fermentum facilisis. Praesent enim enim, gravida ac sodales sed, placerat id erat. Suspendisse lacus dolor, consectetur non augue vel, vehicula interdum libero. Morbi euismod sagittis libero sed lacinia.

        Sed tempus felis lobortis leo pulvinar rutrum. Nam mattis velit nisl, eu condimentum ligula luctus nec. Phasellus semper velit eget aliquet faucibus. In a mattis elit. Phasellus vel urna viverra, condimentum lorem id, rhoncus nibh. Ut pellentesque posuere elementum. Sed a varius odio. Morbi rhoncus ligula libero, vel eleifend nunc tristique vitae. Fusce et sem dui. Aenean nec scelerisque tortor. Fusce malesuada accumsan magna vel tempus. Quisque mollis felis eu dolor tristique, sit amet auctor felis gravida. Sed libero lorem, molestie sed nisl in, accumsan tempor nisi. Fusce sollicitudin massa ut lacinia mattis. Sed vel eleifend lorem. Pellentesque vitae felis pretium, pulvinar elit eu, euismod sapien.
      operationId: findPets
      parameters:
        - name: tags
          in: query
          description: tags to filter by
          required: false
          style: form
          schema:
            type: array
            items:
              x-taxi-type:
                name: petstore.Tag
              type: string
```

--------------------------------

### Query Kafka Topic Stream

Source: https://orbitalhq.com/docs/guides/apis-databases-kafka

This snippet demonstrates how to initiate a stream query on a Kafka topic named 'NewFilmReleaseAnnouncement'. It's the first step in processing real-time data from Kafka.

```OrbitalQL
stream { NewFilmReleaseAnnouncement }
```

--------------------------------

### TaxiQL Project from Predefined to Predefined Type

Source: https://orbitalhq.com/docs/querying/writing-queries

This example shows how to project data from one predefined model ('Purchases') to another ('CustomerTransaction') using TaxiQL. It maps fields between the two types.

```TaxiQL
model Purchase {
   transactionId : TransactionId
   customerId : CustomerId
}
model CustomerTransaction {
  transactionId : TransactionId
  name : CustomerName
  price : Price
}

find { Purchases[] } as CustomerTransaction[]
```

--------------------------------

### Native MongoDB Aggregations - GET /products

Source: https://orbitalhq.com/docs/describing-data-sources/mongodb

Retrieves product data using native MongoDB aggregation pipelines for complex data transformations and filtering.

```APIDOC
## GET /products/by-category

### Description
Retrieves products filtered by a specific category ID, sorted by price in descending order.

### Method
GET

### Endpoint
/products/by-category

### Parameters
#### Query Parameters
- **categoryId** (CategoryId) - Required - The ID of the category to filter products by.

### Response
#### Success Response (200)
- **Product[]** - An array of Product objects matching the category.

#### Response Example
```json
[
  {
    "id": "prod1",
    "name": "Laptop",
    "categoryId": "electronics",
    "price": 1200.00
  },
  {
    "id": "prod2",
    "name": "Mouse",
    "categoryId": "electronics",
    "price": 25.00
  }
]
```

## GET /products/paginated

### Description
Retrieves products with pagination, returning a subset of products based on offset and page size, along with metadata about the total records and pages.

### Method
GET

### Endpoint
/products/paginated

### Parameters
#### Query Parameters
- **offset** (Int) - Required - The number of records to skip.
- **pageSize** (Int) - Required - The number of records to return per page.

### Response
#### Success Response (200)
- **ProductPage** - An object containing the paginated products and pagination metadata.

#### Response Example
```json
{
  "results": [
    {
      "id": "prod3",
      "name": "Keyboard",
      "categoryId": "electronics",
      "price": 75.00
    }
  ],
  "metadata": {
    "totalRecords": 100,
    "page": 1,
    "totalPages": 10
  }
}
```
```

--------------------------------

### OpenAPI Spec Context Configuration (taxi.conf)

Source: https://orbitalhq.com/docs/workspace/projects

Example `taxi.conf` file providing context for an OpenAPI specification, including `defaultNamespace` and `serviceBasePath`. This file should be named identically to the OpenAPI spec file but with a `.taxi.conf` extension.

```toml
defaultNamespace: "com.petflix.pets"
serviceBasePath: "https://petflix.com"
```

--------------------------------

### Writing a Simple Greeting Function (Kotlin)

Source: https://orbitalhq.com/docs/extending/custom-functions

A basic example of a Kotlin function implementing `TaxiFunctionProvider` and using `@TaxiFunction` and `@TaxiParam` annotations. This function takes a name and returns a greeting.

```kotlin
package com.acme.functions

class GreetingFunctions : TaxiFunctionProvider {
   @TaxiFunction(description = "Greets a user by name")
   fun greet(@TaxiParam(name = "name") name: String): String =
      "Hello, $name"
}
```

--------------------------------

### OrbitalHQ Mongo MultiAggregation Example

Source: https://orbitalhq.com/docs/describing-data-sources/mongodb

Demonstrates how to define a service method using @MultiAggregation to process user events through multiple aggregation pipelines. It showcases transactional execution and specifies collection names and aggregation stages.

```orbital
import com.orbitalhq.mongo.MultiAggregation
import com.orbitalhq.mongo.MongoService

@MongoService(connection = "usersMongo")
service UserService {
   @MultiAggregation(
      transactional = true,
      pipelines = [
         {
            collection: "user_events",
            stages: [
               '{ $match: { processed: false } }',
               '{ $group: { _id: "$userId", eventCount: { $sum: 1 } } }'
            ]
         },
         {
            collection: "user_stats",
            stages: [
               '{ $merge: { into: "user_stats", on: "_id", whenMatched: "merge" } }'
            ]
         }
      ]
   )
   write operation processUserEvents(): ProcessingResult[]
}
```

--------------------------------

### Write Static Value to Kafka Topic with Orbital HQ

Source: https://orbitalhq.com/docs/describing-data-sources/kafka

A simple example demonstrating how to define a static data structure and publish it to a Kafka topic using a previously defined write operation.

```Orbital HQ
given { stockPrice : StockPrice = 
  {
    symbol : 'AAPL',
    price : 12.00203,  
  } 
}
call MyKafkaService::publishStockPrice
```

--------------------------------

### Declare HTTP GET Stub in Nebula (Kotlin)

Source: https://orbitalhq.com/docs/testing/stubbing-services

Example of defining an HTTP GET endpoint stub using Nebula's Kotlin DSL. This stub responds to requests at `/ticketPrices/{cinemaId}` with a JSON object containing a random ticket price.

```kotlin
 http {
    get("/ticketPrices/{cinemaId}") { call ->
       val price = Random.nextDouble(9.99, 19.99).toBigDecimal().setScale(2, RoundingMode.HALF_UP)
       call.respondText("{ \"price\" : $price }", ContentType.parse("application/json"))
    }
 }
```

--------------------------------

### Create New Taxi Project

Source: https://orbitalhq.com/docs/guides/installing

Initializes a new Taxi project in an empty directory. This command prompts the user for project details such as group, name, version, and source directory. It generates necessary configuration files and the source directory structure.

```shell
$ mkdir orbital-demo
$ cd orbital-demo
$ taxi init

You’ll be prompted with questions about the project group, name, version and src:

Project group (eg., com.acme): com.demo
Project name: hello-world
Project version [0.1.0]: 
Source directory [src/]: 
Creating project com.demo/hello-world v0.1.0 in directory /dev/orbital-demo 
Writing config to /dev/orbital-demo/taxi.conf 
Generating source directory at /dev/orbital-demo/src 
Finished 


```

--------------------------------

### Expose Taxi Query as HTTP Operation

Source: https://orbitalhq.com/docs/querying/queries-as-endpoints

Annotate a Taxi query with `@HttpOperation` to expose it as an HTTP endpoint. The `url` must start with `/api/q` and `method` can be GET, POST, PUT, or DELETE. Path variables can be defined using `{myVar}` and accessed with `@PathVariable`.

```taxi
import taxi.http.HttpOperation
import taxi.http.PathVariable

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

--------------------------------

### Launch Orbital Developer Environment

Source: https://orbitalhq.com/docs/guides/installing

Launches the Orbital developer environment for the current project. This command downloads a `docker-compose.yml` file and runs `docker compose up`, configuring Orbital to work with the project. Live reload is enabled by default.

```shell
$ taxi orbital

```

--------------------------------

### Expose S3 Data as HTTP Endpoint using OrbitalHQ

Source: https://orbitalhq.com/docs/describing-data-sources/aws-services

This example demonstrates how to expose data read from S3 as an HTTP GET endpoint. It uses the `HttpOperation` annotation to define the URL and method, allowing clients to query the TradeSummary data via a REST API.

```taxi
import taxi.http.HttpOperation

@HttpOperation(url = "/api/q/trades", method = "GET")
find { TradeSummary[] }
```

--------------------------------

### Build REST API Reading from MongoDB in OrbitalHQ

Source: https://orbitalhq.com/docs/describing-data-sources/mongodb

Provides an example of creating a REST API endpoint using OrbitalHQ to fetch stock prices from MongoDB. It utilizes the previously defined models and services, setting up an HTTP GET operation that accepts a stock symbol as a path variable.

```orbitalscript
@HttpOperation(url = "/api/q/stockPrices/{symbol}", method = "GET")
query FetchStockPrices(@PathVariable("symbol") symbol:StockSymbol) {
  find { SavedStockPrice( StockSymbol == symbol) }
}
```

--------------------------------

### Define MySQL Database Connection in connections.conf

Source: https://orbitalhq.com/docs/describing-data-sources/databases

This example shows the configuration for a MySQL database connection in the connections.conf file. It includes the connection name, JDBC driver, and necessary connection parameters like database, host, password, port, and username.

```HOCON
jdbc {
    mysql-docker {
        connectionName=mysql-docker
        connectionParameters {
            database=test
            host=localhost
            password=my-secret-pw
            port="3306"
            username=root
        }
        jdbcDriver=MYSQL
    }
}
```

--------------------------------

### Taxi Error JSON Output Example

Source: https://orbitalhq.com/docs/querying/errors

An example of the JSON output generated when throwing the `BadPermissionsError` with the specified payload. This showcases the structure defined by the `@ResponseBody` annotation.

```JSON
{
  "errorCode" : "E1234",
  "message" : "You didn't say the magic word"
}
```

--------------------------------

### Initialize a Taxi Project

Source: https://orbitalhq.com/docs/guides/generating-kotlin-from-taxi

Commands to create and navigate into a new Taxi project directory. This sets up the basic structure for a Taxi project.

```bash
mdkir my-taxi-project
cd my-taxi-project
taxi init
```

--------------------------------

### Initialize New Orbital Project (Shell)

Source: https://orbitalhq.com/docs/guides/working-with-xml

This command initializes a new Taxi project, which forms the foundation for an Orbital application. It typically involves interactive prompts to set up the project structure and configuration.

```Shell
taxi init
```

--------------------------------

### Docker Compose for Passing Orbital Options

Source: https://orbitalhq.com/docs/deploying/configuring-orbital

This Docker Compose configuration demonstrates how to pass Orbital application configuration settings using the `OPTIONS` environment variable. It shows setting database credentials and host.

```yaml
services:
   orbital:
      image: orbitalhq/orbital:latest
      environment:
         OPTIONS: >-
            --vyne.db.username=orbital
            --vyne.db.password=changeme
            --vyne.db.host=postgres

```

--------------------------------

### Query Parameters

Source: https://orbitalhq.com/docs/describing-data-sources/http

Demonstrates using query parameters in HTTP requests, including optional parameters.

```APIDOC
## Query Parameters

### Description
Illustrates how to use query parameters (Query Strings) in HTTP requests, including how to define optional parameters.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
```taxi
import taxi.http.QueryVariable

service PersonApi {
  @HttpOperation(method = "GET", url = "https://people.com/people")
  operation listPeople(
       @QueryVariable("apiKey") apiKey: ApiKey?
  ): Person[]
}

// Query to invoke with optional parameter:
given { apiKey: ApiKey = "123" }
find { Person[] }
```

### Response
N/A
```

--------------------------------

### Mapping Fields in Traditional Schemas

Source: https://orbitalhq.com/docs/introduction

This example illustrates the manual mapping of fields between different systems using traditional schema definitions. It highlights the brittleness of this approach, where changes to field names in one system can break integrations, and the mapping logic needs to be duplicated for every consumer.

```Informal Schema Mapping
// The id attribute in the Customer model from the Accounts sytems
// is the same as the custId attribute in the Purchase model from sales system
namespace accounts {
   model Customer {
     id : String  // This is the same...
   }
}
namespace sales {
   model Purchase {
      custId : String //...as this
   }
}
```

--------------------------------

### WebSocket Operation

Source: https://orbitalhq.com/docs/querying/queries-as-endpoints

Queries annotated with @WebsocketOperation can be published over a WebSocket. The path must start with /api/s.

```APIDOC
## POST /api/s

### Description
Exposes a streaming Taxi query as a WebSocket endpoint. The endpoint path is defined in the `@WebsocketOperation` annotation and must start with `/api/s`.

### Method
POST (for establishing WebSocket connection)

### Endpoint
/api/s/{your_custom_path}

### Parameters
#### Path Parameters
None explicitly defined for the WebSocket operation itself, but can be part of the endpoint path if specified in `@WebsocketOperation`.

#### Query Parameters
None.

#### Request Body
None.

### Request Example
(WebSocket connection establishment)

### Response
#### Success Response (WebSocket Stream)
- **(type)** - Description depends on the query's `stream` clause.

#### Response Example
(Data streamed over WebSocket)
```

--------------------------------

### HTTP Operation

Source: https://orbitalhq.com/docs/querying/queries-as-endpoints

Queries annotated with @HttpOperation are automatically converted into HTTP endpoints. The url must start with /api/q.

```APIDOC
## POST /api/q

### Description
Exposes a saved Taxi query as an HTTP endpoint. The endpoint URL is defined in the `@HttpOperation` annotation and must start with `/api/q`.

### Method
GET, POST, PUT, DELETE (specified in `@HttpOperation`)

### Endpoint
/api/q/{your_custom_path}

### Parameters
#### Path Parameters
- **{variableName}** (type) - Required - Defined in the `@HttpOperation` URL and annotated with `@PathVariable` in the query.

#### Query Parameters
None explicitly defined, but can be inferred from query parameters if not handled by path parameters or request body.

#### Request Body
- **(type)** - Required for POST/PUT - The structure is defined by the `@RequestBody` annotation on the query parameter.

### Request Example
```json
{
  "key": "value"
}
```

### Response
#### Success Response (200)
- **(type)** - Description depends on the query's `find` or `stream` clause.

#### Response Example
```json
{
  "field1": "value1",
  "field2": "value2"
}
```
```

--------------------------------

### Define HTTP Services and Operations

Source: https://orbitalhq.com/docs/describing-data-sources/http

Demonstrates how to define services with HTTP operations using annotations for methods and URLs. Supports defining operations with parameters and return types. These examples show basic service definitions for fetching movies and actors.

```Taxi
service MovieService {
   @HttpOperation(method = "GET" , url = "https://myMovies/movies")
   operation findAllMovies() : Movie[]

   @HttpOperation(method = "GET" , url = "https://myMovies/movies/{id}")
   operationFindMovie( @PathVariable(name = "id") id : MovieId ) : Movie
}

@HttpService(baseUrl = "http://actorService")
service ActorService {
   // resolves to http://actorService/actors
   @HttpOperation(method = "GET" , url = "/actors")
   operation findAllActors() : Actor[]
}
```

--------------------------------

### Configure Hazelcast Connection (Simple)

Source: https://orbitalhq.com/docs/describing-data-sources/hazelcast

Defines a basic Hazelcast connection in `connections.conf` by specifying a list of addresses. This is the simplest way to enable Hazelcast as a data source.

```conf
hazelcast {
   myHazelcast {
      connectionName = myHazelcast
      addresses = ["localhost:5701"]
   }
}
```

--------------------------------

### Filter Kafka Stream Data

Source: https://orbitalhq.com/docs/describing-data-sources/kafka

This example demonstrates how to filter messages from a Kafka topic. It reads all messages but only emits those where the `StockTicker` is equal to 'AAPL'.

```orbital
stream { StockPrice.filterEach( ( StockTicker ) -> StockTicker == 'AAPL' ) }
```

--------------------------------

### Semantic Query Example (TaxiQL)

Source: https://orbitalhq.com/docs/background/intro-to-semantic-integration

Demonstrates a semantic query using TaxiQL, abstracting away the data source and join logic. This allows consumers to request data based on its meaning, not its structure.

```taxiql
```
given { ActorId = 1 }
find {
   actorName : ActorName
   agentName : AgentName
}
```
```

--------------------------------

### Define Taxi Types

Source: https://orbitalhq.com/docs/guides/generating-kotlin-from-taxi

Example of defining types within a '.taxi' file. These types represent data structures used in the Taxi project.

```taxi
type FilmId inherits Int
type FilmTitle inherits String
type ReviewScore inherits Int
type ReviewText inherits String
```

--------------------------------

### Build Taxi Project

Source: https://orbitalhq.com/docs/guides/generating-kotlin-from-taxi

Command to build the Taxi project. This command verifies the project's syntax and can generate code if configured.

```bash
taxi build
```

--------------------------------

### Update Service Type Mapping

Source: https://orbitalhq.com/docs/guides/apis-databases-kafka

Modify the type mapping for API operation parameters to ensure data consistency between different data sources.

```APIDOC
## Update Service Type Mapping

### Description
Update the type of an input parameter for an API operation to link it with a corresponding type from another data source (e.g., database schema).

### Method
PUT

### Endpoint
/api/services/{serviceName}/operations/{operationName}/parameters/{parameterName}

### Parameters
#### Path Parameters
- **serviceName** (string) - Required - The name of the service.
- **operationName** (string) - Required - The name of the API operation.
- **parameterName** (string) - Required - The name of the parameter to update.

#### Request Body
- **type** (string) - Required - The new type name to assign to the parameter (e.g., "FilmId").

### Request Example
```json
{
  "type": "FilmId"
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the type update.
- **message** (string) - A message confirming the type mapping update.

#### Response Example
```json
{
  "status": "success",
  "message": "Parameter 'filmId' type updated to 'FilmId'."
}
```
```

--------------------------------

### Launch Orbital Developer Environment (Shell)

Source: https://orbitalhq.com/docs/guides/working-with-xml

This command launches the Orbital developer environment using Docker Compose. It sets up a local, live-reloading environment for your Taxi project, facilitating rapid development and testing.

```Shell
taxi orbital
```

--------------------------------

### Define an API Service for Data Enrichment (Java)

Source: https://orbitalhq.com/docs/describing-data-sources/databases

Defines a service that interacts with an external API to retrieve data. This example uses @HttpOperation to specify the API endpoint and HTTP method.

```java
closed model CustomerBalance {
   customerId : CustomerId
   balance : CurrentBalance
}

service AccountBalanceService {
   @HttpOperation(url="https://fakeurl/customers/{id}/balance", method = "GET" )
   operation getCustomerBalance(@PathVariable id:CustomerId):CustomerBalance
}
```

--------------------------------

### Orbital Workspace Configuration for API Discovery

Source: https://orbitalhq.com/docs/guides/composing-api-and-database

Configuration file for Orbital, defining projects to load. It specifies paths to Taxi definitions and an OpenAPI specification, along with loader details like package type, identifier, and default namespace for API discovery.

```hcl
file {
   projects = [
      {path: "taxi/taxi.conf"},
      {
         path: "services/api-docs.yaml",
         loader: {
            packageType: OpenApi
            identifier: {
               organisation: "com.petflix"
               name: "PetflixServices"
               version: "0.1.20"
            },
            defaultNamespace: "com.petflix"
         }
      }
   ]
}
```

--------------------------------

### Building a REST API that reads from MongoDB

Source: https://orbitalhq.com/docs/describing-data-sources/mongodb

Demonstrates how to create an HTTP endpoint that accepts a GET request with a ticker symbol to fetch stock prices from MongoDB.

```APIDOC
## Building a REST API that reads from Mongo

### Description
This is a full example, where we create an HTTP endpoint accepting a `GET` request with a ticker symbol. We use the same models and services declared in Streaming data from Kafka to Mongo.

### HTTP Operation

- **URL**: `/api/q/stockPrices/{symbol}`
- **Method**: `GET`

### Query

- **Name**: `FetchStockPrices`
- **Parameters**:
  - `symbol` (StockSymbol) - Path Variable (`@PathVariable("symbol")`)
- **Logic**: `find { SavedStockPrice( StockSymbol == symbol) }`
```

--------------------------------

### TaxiQL Projection Scope for Customer Array

Source: https://orbitalhq.com/docs/querying/writing-queries

This TaxiQL example demonstrates defining a projection scope for an array of 'Customer' objects, projecting individual fields for each customer.

```TaxiQL
find { Customer[] } as { // start a projection scope. 
   // Within the scope, each item is an individual Customer instance
   firstName : FirstName
}[] // Be sure to include the array marker at the end, as the object is an array.
```

--------------------------------

### TaxiQL Find All Movies Query

Source: https://orbitalhq.com/docs/querying/writing-queries

This query demonstrates the basic syntax in TaxiQL to find all records of the 'Movie' type. It's a foundational example for data retrieval.

```TaxiQL
// Find all the movies
find { Movie[] }
```

--------------------------------

### Orbital SAML Configuration Arguments

Source: https://orbitalhq.com/docs/deploying/authentication

These command-line arguments are used to configure SAML authentication within your Orbital application. They specify whether SAML is enabled, keystore details, IdP metadata file path, service provider entity ID, callback URL, and service provider metadata resource path.

```shell
--vyne.security.saml.enabled=true
--vyne.security.saml.keyStorePath=/opt/serviuce/orbital/saml.jks
--vyne.security.saml.keyStorePassword=orbital
--vyne.security.saml.privateKeyPassword=orbital
--vyne.security.saml.idpMetadataFilePath=/op/service/orbital/okta-idp-metadata.xml
--vyne.security.saml.serviceProviderEntityId=http://okta-sample.orbital.io
--vyne.security.saml.callbackBaseUrl=http://localhost:9022
--vyne.security.saml.serviceProviderMetadataResourcePath=/opt/service/orbital/sp-orbital-metadata.xml
```

--------------------------------

### GET /api/q/meta/{nameOfQuery}/oas (OpenAPI Specification)

Source: https://orbitalhq.com/docs/querying/queries-as-endpoints

Retrieves the OpenAPI specification for a given query endpoint. This allows for automated client generation and API interaction documentation.

```APIDOC
## GET /api/q/meta/{nameOfQuery}/oas

### Description
Retrieves the OpenAPI specification for a specified query.

### Method
GET

### Endpoint
/api/q/meta/{nameOfQuery}/oas

### Parameters
#### Path Parameters
- **nameOfQuery** (string) - Required - The name of the query for which to retrieve the OpenAPI specification.

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl -X GET 'http://localhost:9022/api/q/meta/findMoviesAndReviews/oas'
```

### Response
#### Success Response (200 OK)
- **OpenAPI Specification** (object) - The OpenAPI (Swagger) specification for the query in JSON format.

#### Response Example
```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "findMoviesAndReviews API",
    "version": "1.0.0"
  },
  "paths": {
    "/api/findMoviesAndReviews": {
      "get": {
        "summary": "Finds movies and their reviews.",
        "responses": {
          "200": {
            "description": "A list of movies and reviews."
          }
        }
      }
    }
  }
}
```
```

--------------------------------

### GET /api/q/newReleases (Server-Sent Events)

Source: https://orbitalhq.com/docs/querying/queries-as-endpoints

This endpoint publishes query results over HTTP as Server-Sent Events. It allows clients to stream real-time updates for new release announcements.

```APIDOC
## GET /api/q/newReleases

### Description
Publishes query results for new release announcements as Server-Sent Events over HTTP.

### Method
GET

### Endpoint
/api/q/newReleases

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl -X GET 'http://localhost:9022/api/q/newReleases' \
  -H 'Accept: text/event-stream;charset-UTF-8'
```

### Response
#### Success Response (200 OK)
Content-Type: text/event-stream

Data is streamed in Server-Sent Events format.

#### Response Example
```json
{
  "event": "message",
  "data": "{\"title\": \"Movie Title\", \"reviewScore\": 8.5}"
}
```
```

--------------------------------

### Enrich OpenAPI Spec with Taxi Types

Source: https://orbitalhq.com/docs/workspace/overview

This example shows how to enrich an OpenAPI specification by adding a custom semantic type (`CustomerId`) to a field (`custId`) using the `x-taxi-type` extension.

```YAML
# An extract of the ShoppingCartApi OpenAPI spec:
components:
 schemas:
 ShoppingCart:
 properties:
 custId: # Field name
 x-taxi-type:
 > name: CustomerId # <-- Semantic type
 type: string
```

--------------------------------

### Taxi Function Declaration (Taxi DSL)

Source: https://orbitalhq.com/docs/extending/custom-functions

Example of declaring a custom function within a Taxi namespace. This ensures that functions are organized and avoids potential naming collisions.

```taxi
namespace com.acme.functions

declare function greet(name: String): String
```

--------------------------------

### Path Variables

Source: https://orbitalhq.com/docs/describing-data-sources/http

Illustrates how to use path variables in HTTP requests.

```APIDOC
## Path Variables

### Description
Shows how to use path variables in HTTP requests, ensuring semantic types are used for matching.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
```taxi
import taxi.http.PathVariable
service PetApi {
   @HttpOperation(method = "GET", url = "https://pets.com/pets/{petId}")
   operation getPetById(@PathVariable("petId") id: PetId): Pet
}

// Query to invoke:
given { pet: PetId = "123" }
find { Pet }
```

### Response
N/A
```

--------------------------------

### Insert Static Data into Hazelcast

Source: https://orbitalhq.com/docs/describing-data-sources/hazelcast

Example of inserting a static `Film` object into Hazelcast using the `HazelcastService::upsert` operation. This demonstrates a direct data insertion.

```taxi
// inserting a static value into Hazelcast
given { film : Film = 
  {
    filmId : 123,
    title : "Star Wars",  
    languages : ["English" , "American" ]
  }
}
call HazelcastService::upsert
```

--------------------------------

### Configure Query Parameter Authentication in auth.conf

Source: https://orbitalhq.com/docs/describing-data-sources/authentication-to-services

This HOCON example configures authentication using a query parameter. It specifies the service name, type, the name of the query parameter, and its value.

```hocon
authenticationTokens {

  // The fully qualified name of a service, as defined in a taxi schema. 
  // Should be surrounded in quotes.
  "com.foo.TestService" {
     type: QueryParam
     parameterName: authKey
     value: letMeIn
  }
}

```

--------------------------------

### Http Headers in Operations

Source: https://orbitalhq.com/docs/describing-data-sources/http

Demonstrates defining HTTP headers as annotations on operations.

```APIDOC
## Http Headers in Operations

### Description
Shows how to define HTTP headers as annotations on operations, either with fixed values or as inputs.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
```taxi
service MyService {
  @HttpOperation(method = "GET", url = "...")
  @HttpHeader(name = "Consumes", value = "application/json")
  operation findPeople():Person[]
}
```

### Response
N/A
```

--------------------------------

### Configure Git Repository with OpenAPI Spec via HOCON

Source: https://orbitalhq.com/docs/workspace/connecting-a-git-repo

This HOCON configuration extends the basic Git repository setup to include parameters for reading OpenAPI specifications. It adds `packageType`, `defaultNamespace`, `serviceBasePath`, and `identifier` to process OpenAPI documents effectively.

```hocon
git {
   # The root directory where all git repositories are cloned to
   checkoutRoot="/opt/service/orbital/git-root"
   # How frequently Orbital should poll git repositories for changes
   pollFrequency=PT30S
   
   # A collection of Git Repository configurations
   repositories=[
      {
         # Give this repo a name.  
         name=hamilton-taxonomy
         
         # The url (including personal access token) to clone the repo from
         uri="https://alexhamilton:glpat-dundadadadundundun@github.com/orbital/reynolds-pamphlet"
         
         # The branch to monitor
         branch=master

         # The path within the git repo (Optional, by default uses the root) 
         path="/a/path/to/a/folder"

         loader: {
            # Must be OpenApi
            packageType: 'OpenApi'
            
            # Orbital will automatically create services and models
            # from the OpenApi spec, and place them under this namespace.
            # Mandatory.
            defaultNamespace: 'com.hamilton'

            # If the paths specified in the OpenApi spec are relative, 
            # and no base path is specified, then specify one here.
            serviceBasePath: https://hamilton.com/

            # Provides a project identifier for this api spec.
            # Mandatory
            identifier: {
              organisation: acme
              name: hamilton
              # Must be a Semver version
              version: '1.1.0'
            }
         }
      }
   ]
}

```

--------------------------------

### Declare XML Attribute in Orbital

Source: https://orbitalhq.com/docs/data-formats/xml

This example demonstrates how to mark a field within an XML model to be treated as an attribute rather than an element. It uses the `XmlAttribute` annotation from `lang.taxi.xml`.

```Taxi
import com.orbitalhq.formats.Xml
import lang.taxi.xml.XmlAttribute

@Xml
model Actor inherits Person {
    @XmlAttribute
    id : ActorId 
    
    fullName : FullName
}
```

--------------------------------

### Define Additional Sources in Taxi Project (YAML)

Source: https://orbitalhq.com/docs/testing/stubbing-services

Configuration within a Taxi project's `project.toml` (or similar) file to specify additional source directories. This example includes a path for Nebula stub files (`*.nebula.kts`).

```yaml
name: com.acme/demo
version: 0.1.0
sourceRoot: src/
additionalSources: {
   "@orbital/config" : "orbital/config/*.conf",
   "@orbital/nebula" : "orbital/nebula/*.nebula.kts"
}


```
Tokens:
Raw