http-api-design

Design ergonomic JSON HTTP APIs with OpenAPI 3.1 specifications.

3|Updated Feb 11, 2026
One-click install
npx skills add https://github.com/deepnoodle-ai/creddit --skill http-api-design
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: http-api-design
Source: https://github.com/deepnoodle-ai/creddit/tree/main/.claude/skills/http-api-design
Command: npx skills add https://github.com/deepnoodle-ai/creddit --skill http-api-design

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Design and implement ergonomic JSON HTTP APIs for machine-to-machine communication. This skill helps teams design API endpoints and OpenAPI specs to produce consistent, machine-friendly HTTP JSON APIs, enabling clearer contracts and easier integration.

Core Features & Use Cases

  • OpenAPI-first workflow: Draft an OpenAPI 3.1 spec before implementation to establish a single source of truth for contracts.
  • Resource-oriented design: Model domains as resources with proper HTTP methods, status codes, and clean URL structures.
  • Consistency & error handling: Enforce uniform response envelopes (data), error formats, and predictable behavior across services.
  • Use Case: Designing an offers API with endpoints like /offers and /offers/{offer_id} using snake_case payloads.

Quick Start

Draft a minimal OpenAPI 3.1 specification following these conventions to start implementing a RESTful HTTP API.

Frequently Asked Questions about http-api-design

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

FAQPage Schema
How do I design a REST API with OpenAPI 3.1 for machine-to-machine communication?

To design a machine-to-machine REST API, draft an OpenAPI 3.1 specification first to establish a single source of truth, modeling domains as resources with proper HTTP methods, clean URLs, and snake_case JSON payloads.

What is the best way to structure HTTP API error responses for consistent integration?

The best way to structure HTTP API error responses is using RFC 9457 compliant error envelopes, ensuring uniform response formats and predictable behavior across services for easier machine integration.

How do I create resource-oriented URLs for an HTTP JSON API?

Create resource-oriented URLs by modeling domains as resources with proper HTTP methods and status codes, using clean URL structures like `/offers` and `/offers/{offer_id}` for your JSON API endpoints.

Does this API design approach support OpenAPI-first workflow before implementation?

Yes, the API design approach supports an OpenAPI-first workflow, allowing you to draft an OpenAPI 3.1 specification before implementation to establish clear contracts and consistent, machine-friendly HTTP JSON APIs.

Why use snake_case for JSON API payloads in machine-to-machine communication?

Using snake_case for JSON API payloads enforces consistency across your HTTP API, which is critical for machine-to-machine communication to ensure predictable data parsing and easier client integration.

What HTTP semantics should I follow when designing machine-friendly HTTP APIs?

When designing machine-friendly HTTP APIs, follow resource-oriented design that enforces consistency with HTTP semantics, utilizing proper HTTP methods, standard status codes, and clean URL structures for reliable communication.