Typespec API Operations

TypeSpec API operations

Add RESTful operations to an existing TypeSpec API plugin by selecting the correct verb, route, parameter decorators, request/response models, confirmation capability, and optional adaptive card output.

When to invoke

• "Add TypeSpec API operations for this plugin."
• "Create GET, POST, PATCH, and DELETE operations in TypeSpec."
• "Add a GitHub Copilot plugin CRUD endpoint with @route and @card."
• "Why is my TypeSpec parameter not showing in GitHub Copilot?"
• "Add confirmations and adaptive cards to these operations."

Operation patterns

Use parameter names such as userId consistently, and preserve status unions like "active" | "completed". Use adaptive-card conditional syntax ${if(..., ..., 'N/A')} when documenting generic data binding.

Use RESTful conventions: GET /items, GET /items/{id}, POST /items, PATCH /items/{id}, and DELETE /items/{id}. Group related operations in the same namespace and use nested routes only for hierarchical resources.

Models, parameters, and responses

@service
@server("https://api.example.com")
@actions(#{
  nameForHuman: "Items API",
  descriptionForHuman: "Manage items",
  descriptionForModel: "Read, create, update, and delete items"
})
namespace ItemsAPI {
  model Item {
    @visibility(Lifecycle.Read)
    id: integer;
    userId: integer;
    title: string;
    description?: string;
    status: "active" | "completed" | "archived";
    @format("date-time")
    createdAt: utcDateTime;
    @format("date-time")
    updatedAt?: utcDateTime;
  }

  model CreateItemRequest {
    userId: integer;
    title: string;
    description?: string;
  }

  model UpdateItemRequest {
    title?: string;
    description?: string;
    status?: "active" | "completed" | "archived";
  }

  model ItemList {
    items: Item[];
    total: integer;
    hasMore: boolean;
  }

  model DeleteResponse {
    success: boolean;
    message: string;
    deletedId: integer;
  }

  model ErrorResponse {
    error: {
      code: string;
      message: string;
      details?: string[];
    };
  }
}

Adaptive cards and confirmations

Attach cards to read operations when GitHub Copilot should render structured results. Keep cards focused, test data binding with actual API responses, use conditional rendering such as ${if(description, description, 'N/A')}, and include action buttons only for common next steps.

@route("/items")
@card(#{
  dataPath: "$",
  title: "$.title",
  file: "item-card.json"
})
@get op listItems(@query userId?: integer): Item[];

Create appPackage/item-card.json:

{
  "type": "AdaptiveCard",
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "version": "1.5",
  "body": [
    {
      "type": "Container",
      "$data": "${$root}",
      "items": [
        { "type": "TextBlock", "text": "**${if(title, title, 'N/A')}**", "wrap": true },
        { "type": "TextBlock", "text": "${if(description, description, 'N/A')}", "wrap": true }
      ]
    }
  ],
  "actions": [
    { "type": "Action.OpenUrl", "title": "View Details", "url": "https://example.com/items/${id}" }
  ]
}

Add confirmations to destructive operations and any operation that changes important data. Show key details in the confirmation body and state irreversible consequences in text instead of relying on an emoji.

@route("/items/{id}")
@patch
@capabilities(#{
  confirmation: #{
    type: "AdaptiveCard",
    title: "Update Item",
    body: """
    Updating item #{{ function.parameters.id }}:
      * **Title**: {{ function.parameters.item.title }}
      * **Status**: {{ function.parameters.item.status }}
    """
  }
})
op updateItem(@path id: integer, @body item: UpdateItemRequest): Item;

@route("/items/{id}")
@delete
@capabilities(#{
  confirmation: #{
    type: "AdaptiveCard",
    title: "Delete Item",
    body: """
    Are you sure you want to delete item #{{ function.parameters.id }}?
    This action cannot be undone.
    """
  }
})
op deleteItem(@path id: integer): void;

Complete CRUD skeleton

namespace ItemsAPI {
  @route("/items")
  @card(#{ dataPath: "$", title: "$.title", file: "item-card.json" })
  @get op listItems(
    @query userId?: integer,
    @query status?: "active" | "completed" | "archived",
    @query limit?: integer,
    @query offset?: integer
  ): ItemList;

  @route("/items/{id}")
  @card(#{ dataPath: "$", title: "$.title", file: "item-card.json" })
  @get op getItem(@path id: integer): Item | ErrorResponse;

  @route("/items")
  @post
  @capabilities(#{ confirmation: #{ type: "AdaptiveCard", title: "Create Item", body: "Creating: **{{ function.parameters.item.title }}**" } })
  op createItem(@body item: CreateItemRequest): Item;

  @route("/items/{id}")
  @patch
  @capabilities(#{ confirmation: #{ type: "AdaptiveCard", title: "Update Item", body: "Updating item #{{ function.parameters.id }}" } })
  op updateItem(@path id: integer, @body item: UpdateItemRequest): Item;

  @route("/items/{id}")
  @delete
  @capabilities(#{ confirmation: #{ type: "AdaptiveCard", title: "Delete Item", body: "Delete item #{{ function.parameters.id }}?" } })
  op deleteItem(@path id: integer): DeleteResponse;
}

Testing prompts

Troubleshooting

Output template

## TypeSpec API operations - <resource>

**Status:** complete | needs validation | blocked
**Resource:** <resource name>

### Operations added
| Verb | Route | Operation | Request model | Response model | Card/confirmation |
| --- | --- | --- | --- | --- | --- |
| GET | `/items` | `listItems` | none | `ItemList` | `@card` |
| POST | `/items` | `createItem` | `CreateItemRequest` | `Item` | confirmation |

### Files to update
- `<typespec file>`: <operations/models added>
- `appPackage/item-card.json`: <card added or not needed>

### Test prompts
- `<prompt>`

### Validation
- Parameter decorators: pass | fail
- REST routes: pass | fail
- Confirmations for PATCH/DELETE: pass | fail
- Adaptive card JSON: pass | fail | not used

Quality gate

• Each operation uses the correct HTTP decorator: @get, @post, @patch, or @delete.
• Every path token in @route has a matching @path parameter.
• Filters use @query; request payloads use @body; headers use @header.
• Models use ?, union types, @format("date-time"), and @visibility(Lifecycle.Read) where appropriate.
• PATCH and DELETE include confirmations with meaningful details.
• Any @card file exists under appPackage/ and uses valid Adaptive Card JSON.
• Testing prompts cover GET, POST, PATCH, and DELETE when those operations are added.
• Output follows the ## Output template exactly.

References

• Adaptive Card schema
• Example API endpoint
• Example item URL