igmarin/generate-api-collection

Generate API Collection

Core principle: Every API surface (Rails app or engine) has a single API collection file that stays in sync with its endpoints.

Rules at a Glance

| Aspect | Rule | |--------|------| | When | Create or update collection when creating or modifying any REST API endpoint (route + controller action) | | Format | Postman Collection JSON v2.1 (schema or info.schema references v2.1) | | Location | One file per app or engine — docs/api-collections/<app-or-engine-name>.json or spec/fixtures/api-collections/; if a collection folder already exists, update the existing file | | Language | All request names, descriptions, and variable names must be in English | | Variables | Use {{base_url}} for the base URL so the collection works across environments | | Per request | method, URL, headers, body, description, and test scripts (e.g. pm.response.to.have.status(200)) | | Folders | Group related endpoints into folders using nested item arrays | | Exception | GraphQL endpoints — use implement-graphql instead |

HARD-GATE

When you create or modify a REST API endpoint (new or changed route and controller action),
you MUST also create or update the corresponding API collection file so the
flow can be tested. Do not leave the collection missing or outdated.

Each request MUST include a description and at least one basic test script (e.g. status code check).

EXCEPTION: GraphQL endpoints — use implement-graphql instead.

Core Process

1. Create or open the corresponding API collection JSON file.
2. Group related endpoints into folders using nested item arrays.
3. Use {{base_url}} for the base URL.
4. Add method, URL, headers, body, description, and test scripts for each request.
5. Validate the JSON is syntactically correct:
   • Run python -m json.tool collection.json or jq . collection.json — both print errors on invalid JSON.
   • If invalid: fix the reported error, then re-run the command until it exits cleanly.
6. Verify the collection can be imported into a compatible API client (e.g. Postman) without errors.
7. Confirm all new or changed endpoints are represented and that {{base_url}} is used consistently.

Collection Structure (Postman v2.1)

Ensure the collection includes the info block, folders (nested item arrays), and event scripts:

{
  "info": {
    "name": "Products API",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "item": [
    {
      "name": "Products",
      "item": [
        {
          "name": "List products",
          "request": {
            "method": "GET",
            "header": [],
            "url": "{{base_url}}/api/v1/products",
            "description": "Returns a list of all products in the catalog."
          },
          "event": [
            {
              "listen": "test",
              "script": {
                "exec": ["pm.test('Status code is 200', () => { pm.response.to.have.status(200); });"],
                "type": "text/javascript"
              }
            }
          ]
        }
      ]
    }
  ],
  "variable": [
    { "key": "base_url", "value": "http://localhost:3000" }
  ]
}

Common Mistakes

| Mistake | Reality | |---------|----------| | Missing Content-Type or body for POST/PUT | Include headers and example body so the request works out of the box | | Skipping validation after generation | Run jq . or python -m json.tool and fix any errors before committing (see HARD-GATE) |

Extended Resources

Load only when a concrete collection example is needed:

• EXAMPLES.md — Postman v2.1 multi-endpoint collection example.

Integration

| Skill | When to chain | |-------|---------------| | create-engine | When the engine exposes HTTP endpoints | | version-api | When a new version requires a collection update |