Every premium and members-only resource for $9.99/month, as a no-commitment subscription. See the plans

PalateKit

Sign in
Menu

Request a resource

Describe the resource you are missing in one sentence. We will email you when it is published.

0 / 280

A page, a video or an image online.

Unlock PalateKit

Unlock everything

Plan

Paying means accepting our terms of sale.

Secure payment by Stripe. Receipts and invoices sent by email.

Welcome back

Sign in to install, download or save this resource. A free account is enough for free resources.

JSON API design: resources, errors and idempotency v1.0.0

Use this resource to design or review a JSON HTTP API: resources, errors, pagination and idempotency

New

  • 458 downloads
  • 202 likes
  • 117 saves

Free

Install with the CLI

In a terminal, from the folder you want:

npx --yes palatekit@latest install rest-api-design-rules

With no option, the skill goes to ~/.agents/skills/; add --agent claude-code (or codex, cursor…) to target an agent.

First time: connect the CLI with

npx --yes palatekit@latest login

The agent designs or reviews a JSON HTTP API against 52 rules inspired by Stripe's API: resource modelling, identifiers, response format, errors, idempotency, versioning, pagination and webhooks. Each rule explains the why. You get API decisions that are hard to get wrong later.

Mostly picked by

Updated November 2, 2026

Card for the “JSON API design: resources, errors and idempotency” skill

Details

Works in
Install guides
Generates with
Your agent's model
Licence
MIT

Similar resources

View all

What you get

  • references/: cards on errors, their types, codes and HTTP status
  • references/: cards on cursor pagination and nested parameter formats

Good fit for

  • You are defining the public API of a new service
  • Your errors return different shapes on each endpoint

Not for

    Tags

    • api
    • rest
    • json
    • design
    • stripe

    About

    You say

    “Review this OpenAPI spec: the errors have no stable code and pagination uses page numbers.”

    Card for the “JSON API design: resources, errors and idempotency” skill

    Skill published by pproenca under the MIT license, delivered in its original version.

    Show more

    How to use it

    1. Install the skill in your agent's skills folder
    2. Ask your agent to design or review a JSON HTTP API: resources, errors, pagination and idempotency
    3. Review and adjust the result

    Content preview

    Files

    • AGENTS.md13.2 KB
    • assets/templates/_template.md3.7 KB
    • gotchas.md0.6 KB
    • LICENSE1.1 KB
    • metadata.json1.5 KB
    • NOTICE-PALATEKIT.md0.5 KB
    • references/_sections.md3.3 KB
    • references/error-doc-url-on-every-error.md3.7 KB
    • references/error-four-type-enum.md4.2 KB
    • references/error-http-status-mapping.md4.1 KB
    • references/error-lowercase-snake-case-codes.md2.8 KB
    • references/error-message-mandatory-code-optional.md3.8 KB
    • references/error-top-level-object.md3.6 KB
    • references/format-bracket-notation-nesting.md3 KB
    • references/format-cursor-pagination.md3.1 KB
    • references/format-dot-notation-expansion.md3.2 KB
    • references/format-expand-parameter.md3.7 KB
    • references/format-form-encoded-requests.md3.2 KB
    • references/format-list-envelope.md3.1 KB
    • references/format-no-total-counts.md2.7 KB
    • references/idem-24h-ttl.md3.6 KB
    • references/idem-fail-on-key-reuse.md4.7 KB
    • references/idem-key-header.md3.9 KB
    • references/idem-recovery-points.md5 KB
    • references/idem-scoped-per-account.md3.3 KB
    • references/naming-american-english.md4 KB
    • references/naming-boolean-past-tense.md3.5 KB
    • references/naming-enums-over-booleans.md4.5 KB
    • references/naming-metadata-pattern.md4.6 KB
    • references/naming-simple-unambiguous.md4.2 KB
    • references/naming-snake-case-wire-format.md3.5 KB
    • references/naming-type-discriminator-polymorphism.md4.7 KB
    • references/ops-https-only-basic-auth.md4 KB
    • references/ops-on-behalf-of-header.md4.7 KB
    • references/ops-prefixed-api-keys.md4.8 KB
    • references/ops-webhook-at-least-once-handlers-idempotent.md6.4 KB
    • references/ops-webhook-event-envelope.md5 KB
    • references/ops-webhook-event-naming.md5.2 KB
    • references/ops-webhook-signature.md5.6 KB
    • references/resource-birthdate-hash.md2.5 KB
    • references/resource-currency-field-not-name.md2.5 KB
    • references/resource-decimal-suffix-strings.md2.6 KB
    • references/resource-integer-minor-units.md2.7 KB
    • references/resource-iso-date-only.md2.3 KB
    • references/resource-object-discriminator.md2.1 KB
    • references/resource-opaque-ids.md2.3 KB
    • references/resource-prefixed-string-ids.md2.3 KB
    • references/resource-unix-seconds-timestamps.md2.3 KB
    • references/url-action-verbs-as-subpaths.md2.9 KB
    • references/url-dedicated-search-endpoint.md3 KB
    • references/url-no-bulk-endpoints.md3 KB
    • references/url-plural-collections.md2.3 KB
    • references/url-post-for-updates.md2.7 KB
    • references/url-version-in-path-and-header.md2.8 KB
    • references/ver-account-pinning.md3.8 KB
    • references/ver-additive-changes.md5 KB
    • references/ver-dated-versions.md3.4 KB
    • references/ver-tolerate-unknown.md5.4 KB
    • references/ver-version-change-modules.md5.1 KB
    • SKILL.md11.5 KB

    Origin and licence

    Listed unmodified

    Author
    pproenca
    Source
    github.com/pproenca/dot-skills/tree/cf93c57cac89d6fc3e4194686000411567f5caf3/skills/.experimental/stripe-inspired-api-design-rules
    Licence
    MIT

    Notice

    « stripe-inspired-api-design-rules » (pproenca, MIT) livré dans sa version d'origine : fiche en français et en anglais par PalateKit.

    User reviews

    –

    No ratings yet

    Loading reviews…

    Delete your review?

    Your rating and comment will be removed from the page.