orchestrating-api-implementation

Overview

This skill implements APIs and admin screens in Ruby on Rails + PostgreSQL based on API specifications defined in JSON.

When to use this skill

Claude uses this skill in the following situations:

• When the user provides an API specification in JSON format and requests implementation of a Rails API
• When generating a Rails API from the specification of a headless CMS such as microCMS
• When requested to implement an API by referring to an existing JSON specification file (such as app.json)
• When a JSON specification exists for requests such as "implement the API" or "create the admin screen"

Tech stack

Item	Technology
Language	Ruby 3.4
Framework	Ruby on Rails 8.1
Database	PostgreSQL 18
ORM	Active Record

Steps

For details on each step, refer to the files in the steps/ directory.

1. Check the application specification

Details: @steps/01_check_specification.md

Claude reads the JSON specification file and grasps the model structure, field definitions, and relations. Specification format: @references/01_json_specification.md

2. Decide the tech stack

Details: @steps/02_select_tech_stack.md

Claude checks the environment and decides the admin screen approach (ActiveAdmin / Administrate / Hotwire).

3. Identify use cases

Details: @steps/03_define_usecases.md

Claude checks the actors and use cases in the JSON specification and defines the CRUD operations, pagination, filtering, sorting, and relation retrieval methods for each model.

4. Create the OpenAPI definition

Details: @steps/04_define_openapi.md

Claude defines the API specification in OpenAPI 3.1 format based on the use cases and model definitions.

5. Design the DB schema

Details: @steps/05_design_db_schema.md

Claude maps the types in the JSON specification to PostgreSQL types and designs the tables.

6. Define SQL and indexes

Details: @steps/06_define_sql_and_indexes.md

Claude identifies the SQL executed in the use cases and defines regular indexes and full-text search indexes (GIN + tsvector).

7. Initialize the project

Details: @steps/07_initialize_project.md

Claude creates a Rails 8.1 project and sets up the necessary Gems and configuration.

8. Implement the DB migration

Details: @steps/08_implement_migration.md

Claude creates and runs migration files based on the design.

9. Implement OR mapping

Details: @steps/09_implement_orm.md

Claude implements relations, scopes, and query methods in the Active Record models.

10. Implement validation

Details: @steps/10_implement_validation.md

Claude implements Active Record validations based on the validation settings in the JSON specification.

11. Implement API endpoints

Details: @steps/11_implement_api_endpoints.md

Claude implements RESTful API endpoints (CRUD, pagination, filtering, sorting).

12. Verify API behavior

Details: @steps/12_verify_api.md

Claude verifies API behavior with curl and RSpec, and confirms that there are no N+1 problems.

13. Implement the admin panel

Claude implements the admin panel using the selected approach. Refer to the following files depending on the approach:

• ActiveAdmin: @steps/13a_admin_activeadmin.md
• Administrate: @steps/13b_admin_administrate.md
• Hotwire: @/backend_development/skills/implementing-hotwire-admin/SKILL.md (using an independent skill)
  • Overview and quick reference: @steps/13c_admin_hotwire.md
• Common settings and troubleshooting: @steps/13d_admin_common.md

Note: When implementing a Hotwire admin panel, use the comprehensive implementing-hotwire-admin skill that also includes E2E test design and implementation.

14. Implement an API Playground (optional)

Details: @steps/14_implement_api_playground.md

Claude uses the OpenAPI definition to implement Swagger UI or a custom Playground, and builds an environment where the API can be tested interactively.

File structure

implementing-rails-api/
├── SKILL.md                 # このファイル
├── references/
│   └── 01_json_specification.md  # JSON仕様の定義
└── steps/
    ├── 01_check_specification.md
    ├── 02_select_tech_stack.md
    ├── 03_define_usecases.md
    ├── 04_define_openapi.md
    ├── 05_design_db_schema.md
    ├── 06_define_sql_and_indexes.md
    ├── 07_initialize_project.md
    ├── 08_implement_migration.md
    ├── 09_implement_orm.md
    ├── 10_implement_validation.md
    ├── 11_implement_api_endpoints.md
    ├── 12_verify_api.md
    ├── 13a_admin_activeadmin.md
    ├── 13b_admin_administrate.md
    ├── 13c_admin_hotwire.md
    ├── 13d_admin_common.md
    └── 14_implement_api_playground.md