APIDev.rules

APIDev.rules is a rule set for AI agents that design, review, and implement APIs.

The rules are distilled from The API: 3rd Edition by Sergey Konstantinov and are organized as reusable Markdown source files. The project is intended to produce agent-ready guidance for general API development, REST APIs, and SDK design.

How to use

• Either check out the repo and install skills, or directly download pre-built skills from the dist folder:
  • AGENTS.md
  • api-development skill
  • api-review skill

If you want to support this work, buy "The API: 3rd Edition" on Amazon (hardcover available) or Leanpub.

Status

In review. The initial skill set has been created, and the book content has been distilled into the rules. There are some benchmarks, each comprising the following:

• prompt.md — the prompt used for generating the API design
• <model-name>-<mode>-default.* — the resulting API design generated by the working in the in the default mode (i.e., using standard skills in the platform)
• <model-name>-<mode>-with-skill.* — the resulting API design generated by the working in the using the API design skill.
• assessment-<mode>-<mode>.md — a comparison of the two API designs made by another model (with skill)
• (optional) review-prompt.md — the prompt used for asking for a design review (if not specified, just the generic "Review this API design" prompt was used)
• review-<model-name>-<mode>-default.* — a review of the generated default API design (no skill) generated by the working in the in the default mode (i.e., using standard skills in the platform)
• review-<model-name>-<mode>-with-skill.* — a review of the generated default API design (no skill) generated by the working in the using the API review skill.

Issues and Limitations

I've only conducted limited testing, but some problems seem to recur:

• Models excessively require idempotency tokens and versioning, considering their absence a critical issue.
• Despite my best efforts, I've observed no attempts by LLMs to challenge the error recovery paths or write sample client code to assess the design quality.
• To make Claude AI use the API skill for designing APIs, I had to prepend prompts with "Using API design skill, …"; otherwise, the platform's default skill is used. It worked without any tricks with API review, though.

Building

The skills are constructed from source files located in the src folder. To make a build, run npm install, then npm run build.

License

Dual-licensed under MIT OR BSD-3-Clause. See LICENCE.