Use the Houston API on Astro Private Cloud

Learn how to make requests to your Astro Private Cloud installation using the Houston API.

The Houston API allows you to build applications that provision and manage resources on Astro Private Cloud. You can use the Houston API to perform CRUD operations on entities scoped to the Astronomer platform, including Airflow Deployments, Workspaces, and users.

For example, you can:

• Delete a Deployment
• Look up a Deployment’s resource config
• Add a user to a Workspace
• Make a user a System Administrator

Anything you can do with the Astro Private Cloud UI, you can do programmatically with the Houston API.

To access the interactive API documentation for your Astro Private Cloud installation, go to https://houston.<your-base-domain>/v1.

Schema overview

The Houston API uses the GraphQL API query language. You can make GraphQL requests using standard REST API tools such as HTTP and curl. GraphQL APIs support two main request types: queries and mutations. You can run these requests against objects which are similar to endpoints in REST APIs.

A query is a request for specific information and is similar to a GET request in a REST API. The primary difference between GraphQL queries and REST API queries is that GraphQL queries only return the fields that you specify within your request. For example, consider the following query to retrieve information about a user:

query User {
  users(user: { email: "[e-mail]"} )
  {
    id
    roleBindings {role}
  }
}

The Houston API would only return the ID and role bindings for the user because those are the only fields specified in the query.

A mutation is a request to update data for a specific object. Different mutations exist for creating, updating, and deleting objects. When you write a mutation request, it’s best practice to use variables to store the data you want to update. For example, consider the following example mutation:

mutation workspaceAddUser(
  $workspaceUuid: Uuid = "<your-workspace-uuid>"
  $email: String! = "<user-email-address>"
  $role: Role! = <user-workspace-role>
  $bypassInvite: Boolean! = true
) {
  workspaceAddUser(
    workspaceUuid: $workspaceUuid
    email: $email
    role: $role
    bypassInvite: $bypassInvite
  ) {
    id
  }
}

In this mutation, the values to update are formatted as variables in the first part of the request, then applied in the second half. Variables marked with a ! are required in order for the query to complete. Lastly, the mutation requests the Houston API to return id of the added user to confirm that the mutation was successful. In this way, it’s possible to make a mutation and a query in a single request.

For more basic GraphQL usage rules and examples, see the GraphQL documentation.