sscgen-rest

Generate typed REST struct schemas and JSON response models for HTTP APIs.

3|Updated Nov 9, 2023

Search Tags:#code generation #rest api #json schema #http client #kdl #typed errors #api contract

Ready to run

npx skills add https://github.com/vypivshiy/selector_schema_codegen --skill sscgen-rest

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: sscgen-rest
Source: https://github.com/vypivshiy/selector_schema_codegen/tree/main/.agents/skills/sscgen-rest
Command: npx skills add https://github.com/vypivshiy/selector_schema_codegen --skill sscgen-rest

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Designing a typed API client from raw REST/JSON traffic is slow and error-prone, especially when you must infer response shapes and handle HTTP error cases consistently.

Core Features & Use Cases

Declarative REST/JSON schemas: define (rest)struct plus json response types for strongly typed parsing of HTTP results.
Endpoint-ready request blocks: generate @request definitions (raw HTTP or curl) with typed placeholders for query/path parameters.
Typed error handling: map HTTP statuses to @error <status> <Schema> ... with key-presence and value-equality guards to avoid false positives.

Quick Start

Create a .kdl file that declares json response schemas and a (rest)struct containing @doc, at least one @request with response=<Schema>, and any relevant @error mappings for the statuses you want to discriminate.

Frequently Asked Questions about sscgen-rest

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I generate a typed REST API client from JSON schemas?▼

To generate a typed REST API client from JSON schemas, you define `(rest)struct` and `json` response types in a `.kdl` file, which `ssc-gen generate` uses to produce an HTTP client with consistent result typing.

How can I map HTTP error statuses to typed response schemas?▼

You map HTTP error statuses to typed response schemas using `@error <status> <Schema>` guards within your `(rest)struct`, applying key-presence and value-equality constraints to route errors accurately and avoid false positives.

What's the best way to define API endpoints with typed parameters in KDL?▼

The best way to define API endpoints with typed parameters in KDL is by creating `@request` definitions within `(rest)struct` blocks, using typed placeholders for query and path parameters before running the code generation.

Why do I need at least one @request block in my REST schema?▼

You need at least one `@request` block in your REST schema because strict REST-only KDL rules require it to validate endpoint definitions and ensure the generated HTTP client has valid request-response mappings.

Can I use raw HTTP or curl commands when building API client contracts?▼

Yes, you can use raw HTTP or curl commands when building API client contracts by specifying them inside your `@request` definitions alongside typed placeholders for parameters and assigned `json` response schemas.

What limitations apply to KDL REST schema generation for HTTP clients?▼

KDL REST schema generation for HTTP clients is limited to strict REST-only rules, meaning you can only emit `@request`, `@error`, and `@doc` nodes within `(rest)struct` blocks, restricting other node types.