Core API Routes Defined in CommonGrants: A Complete TypeSpec Reference

The CommonGrants library defines five core HTTP endpoints for opportunity management under the base path /common-grants/opportunities, implementing full CRUD operations via TypeSpec decorators and auto-generated SDK clients.

The hhs/simpler-grants-protocol repository provides a standardized grants data exchange framework using TypeSpec to define API contracts. The core API routes defined in CommonGrants center on the opportunity resource, offering a predictable REST interface for listing, creating, updating, and deleting grant opportunities.

TypeSpec Route Architecture

The routes are declared using TypeSpec decorators in template files. The base @route("/common-grants/opportunities") decorator establishes the root path for all opportunity-related operations.

In templates/quickstart/routes.tsp, the decorator defines the collection-level endpoint. The Express.js template at templates/express-js/src/typespec/main.tsp mirrors this definition, ensuring consistency across different implementation patterns.

CRUD Endpoint Specification

The CommonGrants API implements standard REST conventions with five primary endpoints:

• GET /common-grants/opportunities – Retrieve a paginated list of opportunities
• POST /common-grants/opportunities – Create a new opportunity using the OpportunityCreate schema
• GET /common-grants/opportunities/{id} – Fetch a specific opportunity by UUID
• PATCH /common-grants/opportunities/{id} – Partially update an opportunity using the OpportunityUpdate schema
• DELETE /common-grants/opportunities/{id} – Remove an opportunity permanently

Source File Implementation

Route Declarations in TypeSpec

The foundational route definitions appear in two key template files. The quickstart template (templates/quickstart/routes.tsp) and the Express.js template (templates/express-js/src/typespec/main.tsp) both declare @route("/common-grants/opportunities") to establish the base path. Individual resource operations are implicitly generated by the SDK at the sub-path /{id}.

Express.js Integration

In templates/express-js/src/api/index.ts, the generated routes are registered with an Express application. The comment // Register routers marks the location where the TypeSpec-generated code connects to the Express router, bridging the type definitions to a working HTTP server.

SDK Client Mapping

The TypeScript SDK implementation in lib/ts-sdk/src/client/opportunities.ts maps these HTTP routes to typed client methods. This abstraction allows developers to interact with the API without manually constructing HTTP requests.

Node.js SDK Usage Examples

The @common-grants/sdk package provides typed methods corresponding to each route. Initialize the client with your API key, then call the appropriate opportunity methods.

List opportunities with pagination:

import { CommonGrantsClient } from "@common-grants/sdk";

const client = new CommonGrantsClient({ apiKey: "YOUR_API_KEY" });

async function listOpportunities() {
  const resp = await client.opportunities.list({ page: 1, pageSize: 20 });
  console.log(resp.data);
}
listOpportunities();

Create a new opportunity:

await client.opportunities.create({
  title: "Community Solar Grant",
  description: "Funding for community-owned solar projects",
  amount: 50000,
  deadline: "2025-12-31",
});

Update an existing opportunity:

await client.opportunities.update("opportunity-uuid", {
  amount: 75000,
});

Delete an opportunity:

await client.opportunities.delete("opportunity-uuid");

Summary

• CommonGrants defines five core REST endpoints under the base path /common-grants/opportunities
• Routes are declared in TypeSpec using the @route decorator in templates/quickstart/routes.tsp and templates/express-js/src/typespec/main.tsp
• The API supports full CRUD operations: listing and creating at the collection level, plus retrieval, partial updates, and deletion for individual resources
• The Express.js template registers generated routes in templates/express-js/src/api/index.ts
• The TypeScript SDK at lib/ts-sdk/src/client/opportunities.ts provides type-safe client methods for all endpoints

Frequently Asked Questions

What base path prefix is used for CommonGrants API routes?

All opportunity endpoints use the base path /common-grants/opportunities. This prefix is defined via the @route decorator in the TypeSpec template files and applies to both collection-level and individual resource operations.

Which HTTP verbs are supported for opportunity resources?

The API supports GET and POST at the collection level (/common-grants/opportunities), and GET, PATCH, and DELETE for individual resources (/common-grants/opportunities/{id}). PATCH operations use the OpportunityUpdate schema for partial modifications.

How are the TypeSpec route definitions converted to working endpoints?

The TypeSpec compiler generates server implementations from the decorator definitions. In the Express.js template, these generated routes are registered in templates/express-js/src/api/index.ts at the comment marked // Register routers, connecting the type definitions to Express middleware.

Where is the SDK client implementation located in the repository?

The TypeScript SDK client resides at lib/ts-sdk/src/client/opportunities.ts. This file implements the CommonGrantsClient class that maps method calls like list(), create(), update(), and delete() to the corresponding HTTP routes defined in the TypeSpec files.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}