Skip to content

Tutorial: Compiling Your First Blueprint

In the "Getting Started" tutorial, you used a pre-existing blueprint for the Petstore API. But the true power of Contextually comes from its ability to onboard any API with a machine-readable specification.

This tutorial will guide you through using the cx compile command to automatically generate a complete, working blueprint from a public OpenAPI specification.

What you will learn:

  • How to use the cx compile command.
  • How to inspect the artifacts generated by the compiler.
  • How to use your new, locally-compiled blueprint in the interactive shell.

1. Find an API Specification

The cx compile command needs a source specification to work from. For this tutorial, we'll use the JSONPlaceholder API, a simple and free fake REST API perfect for testing.

Its OpenAPI specification is available at this URL: https://jsonplaceholder.typicode.com/openapi.json

2. Run the cx compile Command

Now, let's feed that URL to the compiler. The cx compile command takes the source URL (or a local file path) and a few flags to define the new blueprint package.

Run the following command in your terminal. We don't need to specify an --output directory, as cx will correctly default to your ~/.cx/blueprints folder.

cx compile https://jsonplaceholder.typicode.com/openapi.json \
  --name jsonplaceholder \
  --version v1.0.0 \
  --namespace user

Let's break down the flags:

  • --name: The machine-friendly name for our blueprint.
  • --version: The semantic version for this blueprint package.
  • --namespace: We are compiling this into our user namespace, which is the correct place for personal and experimental blueprints.

Compilation Successful

You should see a ✅ Compilation Successful message, indicating that the blueprint package was created in ~/.cx/blueprints/user/jsonplaceholder/v1.0.0/.

3. Inspect the Generated Artifacts

Navigate to the new directory and see what the compiler created for you:

tree ~/.cx/blueprints/user/jsonplaceholder/v1.0.0

You will see three key files:

  • source_spec.json: An exact copy of the original OpenAPI spec for auditability.
  • schemas.py: A Python file containing Pydantic models for all the data structures (like Post, Comment, User) and parameters defined in the API.
  • blueprint.cx.yaml: The executable heart of the blueprint. It contains the base URL and a list of action_templates automatically generated from the API's paths, like getPosts and createPost.

4. Use Your New Blueprint

Your new blueprint is now ready to be used.

First, create a connection file that points to your new blueprint.

# Create the file in your connections directory
touch ~/.cx/connections/jsonplaceholder.conn.yaml

# Add the following content to the file
echo '
name: "JSONPlaceholder API"
id: "user:jsonplaceholder"
api_catalog_id: "user/jsonplaceholder@v1.0.0"
auth_method_type: "none"
' > ~/.cx/connections/jsonplaceholder.conn.yaml

Now, start the shell and use it!

cx

Inside the shell, connect to your new API and run an action from its blueprint:

# Connect with the alias 'jph'
cx> connect user:jsonplaceholder --as jph

# Run the 'getPosts' action, which was generated by the compiler!
cx> jph.getPosts()

Congratulations! You have successfully onboarded a brand new API onto the Contextually platform with a single command and are now interacting with it dynamically. This is the core workflow for expanding the Blueprint Ecosystem.