# Core API Routes Defined in CommonGrants: A Complete TypeSpec Reference

> Explore the core API routes in CommonGrants, a TypeSpec reference detailing five HTTP endpoints for opportunity management with full CRUD operations and auto-generated SDK clients.

- Repository: [U.S. Department of Health & Human Services/simpler-grants-protocol](https://github.com/hhs/simpler-grants-protocol)
- Tags: api-reference
- Published: 2026-03-03

---

**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`](https://github.com/hhs/simpler-grants-protocol/blob/main/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`](https://github.com/hhs/simpler-grants-protocol/blob/main/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:

```typescript
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:

```typescript
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:

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

```

Delete an opportunity:

```typescript
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`](https://github.com/hhs/simpler-grants-protocol/blob/main/templates/express-js/src/api/index.ts)
- The TypeScript SDK at [`lib/ts-sdk/src/client/opportunities.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/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`](https://github.com/hhs/simpler-grants-protocol/blob/main/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`](https://github.com/hhs/simpler-grants-protocol/blob/main/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.