Projects

A Taxi project contains a taxi.conf file, and a collection of files saved with a .taxi extension

We document projects in depth over on the Taxi site.

​

Adding a project

There are various ways to add projects into an Orbital workspace.

• Adding a project from git
• Reading projects from disk
• Modifying your workspace.conf file directly

​

README.md file

If a README.md file is supplied at the root of the project, it will be read by Orbital and displayed in the UI

Github flavored markdown is supported, along with some special code snippets.

​

Taxi snippets

Standard Taxi can be included by using the following syntax:

```taxi
@DatabaseService(connection = "my-postgres-db")
service MyPostgresService {

   // table declares read operations, such as querying
   table ticketSales : VenueTicketSalesRecord[]
   
   // An upsert operation, for performing upsert queries
   @UpsertOperation
   write operation saveTicketSalesRecord(VenueTicketSalesRecord):VenueTicketSalesRecord
}
```

​

TaxiQL snippets

Taxi queries that can be run in the query editor in Orbital can be included like this:

```taxiql
find { VenueTicketSales[] }
call MyPostgresService::saveTicketSalesRecord
```

​

Schema diagram snippets

Schema diagrams can be included with the following syntax:

```schemaDiagram
{
   "members" : {
      "TicketsS3Bucket" : {},
      "VenueTicketSales" : {},
      "TicketPricesApi" : {}
   }
}
```

This will produce the following interactive component within the README in Orbital:

​

Combining Taxi and other API specs in a single project

Orbital supports extensions to Taxi project files which allow reading other API specs (OpenAPI, Avro) directly from within your Taxi project.

This works well for teams that prefer to keep their API specs and Taxi together.

​

Project layout

Your project should be updated with the following layout:

Define the location of your Avro and/or OpenAPI spec files in the additionalSources section of your taxi.conf file.

For example, the following directory structure:

.
├── src/  # Taxi files go hereWorkspace.conf
├── avro/  # Avro files go hereThe workspace.conf should drop to a single Git project - the project containing the above.
├── openapi/  # OpenAPI files go here
└── taxi.conf  # Additional OpenAPI config

would be configured as follows:

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"
}

​

OpenAPI specs

OpenAPI specs need additional context, beyond what’s available in the spec itself.

These properties must be stored in a file with the same name as the OpenAPI spec, but with a taxi.conf extension (eg: nameOfYourApiSpec.taxi.conf)

For example:

openapi/
├── petflix-api-spec.yaml # Your OpenAPI spec
└── petflix-api-spec.taxi.conf # The taxi conf file for the spec

The contents of that file should be as follows:

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