paasta-api-endpoint

name	paasta-api-endpoint
description	Automates the creation of new PaaSTA API endpoints following established patterns
disable-model-invocation	true
allowed-tools	Read, Edit, Write, Grep, Glob, Bash, AskUserQuestion

PaaSTA API Endpoint Generator

Description

Automates the creation of new PaaSTA API endpoints following established patterns. This skill guides you through adding a new endpoint to the PaaSTA API, including view function, route registration, Swagger/OpenAPI documentation, and comprehensive tests.

Usage

/paasta-api-endpoint

What This Skill Does

This skill will:

1. Gather endpoint requirements interactively
2. Generate a view function in paasta_tools/api/views/
3. Register the route in paasta_tools/api/api.py
4. Add Swagger 2.0 documentation to swagger.json
5. Add OpenAPI 3.0 documentation to oapi.yaml
6. Generate unit tests following PaaSTA conventions
7. Run the OpenAPI code generator
8. Run tests to verify the implementation

When to Use This Skill

Use this skill when you need to:

• Add a new GET/POST/PUT/DELETE endpoint to the PaaSTA API
• Ensure consistency with existing API patterns
• Automatically generate boilerplate code and documentation
• Get comprehensive test coverage from the start

Instructions

When this skill is invoked, follow these steps:

Step 1: Gather Requirements

Ask the user the following questions (use AskUserQuestion tool for better UX):

1. Endpoint purpose: What does this endpoint do? (brief description)
2. HTTP method: GET, POST, PUT, or DELETE?
3. URL pattern: What's the URL path? (e.g., /v1/services/{service}/instances/{instance}/status)
4. Path parameters: What path parameters are needed? (e.g., service, instance, deploy_group)
5. Query parameters: Any query parameters? (optional)
6. Request body: Does this endpoint accept a request body? If yes, what fields?
7. Response structure: What does the response look like? (e.g., {"status": "running", "count": 5})
8. Error cases: What error scenarios should be handled? (e.g., 404 not found, 500 config error)
9. View file: Which view file should contain this endpoint?
   • Use existing: service.py, instance.py, autoscaler.py, etc.
   • Or create new: provide filename
10. Utility functions: What existing utility functions from paasta_tools/utils.py will be used?

Step 2: Generate View Function

Create the view function following this template:

@view_config(route_name="<route_name>", request_method="<METHOD>", renderer="json")
def <function_name>(request):
    """<Docstring describing what this endpoint does>."""
    # Extract parameters from request
    param1 = request.swagger_data.get("param1")
    param2 = request.swagger_data.get("param2")
    soa_dir = settings.soa_dir

    try:
        # Call utility functions to get data
        result = some_utility_function(param1, param2, soa_dir=soa_dir)

        # Build response
        response_body = {"key": result}
        return Response(json_body=response_body, status_code=200)

    except SpecificException as e:
        raise ApiFailure(str(e), 404)

    except AnotherException as e:
        raise ApiFailure(str(e), 500)

Important conventions:

• Import Response from pyramid.response for explicit status codes
• Import ApiFailure from paasta_tools.api.views.exception for error handling
• All imports at the top of the file (no inline imports)
• Use settings.soa_dir to get the SOA configuration directory
• Return 200 for success, 404 for not found, 500 for server errors
• Always include proper error handling with try/except

Step 3: Register Route

Add route registration to paasta_tools/api/api.py:

config.add_route(
    "<route_name>",
    "<url_pattern>",
)

Find the appropriate location (routes are loosely grouped by functionality).

Step 4: Add Swagger 2.0 Documentation

Update paasta_tools/api/api_docs/swagger.json:

1. Add endpoint definition to "paths" section:

"/path/{param}": {
    "get": {
        "responses": {
            "200": {
                "description": "Success description",
                "schema": {
                    "$ref": "#/definitions/ResponseSchema"
                }
            },
            "404": {
                "description": "Not found description"
            }
        },
        "summary": "Brief summary",
        "operationId": "operation_id",
        "tags": ["service"],
        "parameters": [
            {
                "in": "path",
                "description": "Parameter description",
                "name": "param",
                "required": true,
                "type": "string"
            }
        ]
    }
}

2. Add response schema to "definitions" section if needed:

"ResponseSchema": {
    "description": "Schema description",
    "type": "object",
    "properties": {
        "field": {
            "type": "string",
            "description": "Field description"
        }
    },
    "required": ["field"]
}

Nullable fields in Swagger 2.0: For fields that can be null, use the x-nullable extension:

"optional_field": {
    "type": "string",
    "description": "This field can be null",
    "x-nullable": true
}

Step 5: Add OpenAPI 3.0 Documentation

Update paasta_tools/api/api_docs/oapi.yaml:

1. Add schema to components/schemas section:

ResponseSchema:
  description: Schema description
  type: object
  properties:
    field:
      type: string
      description: Field description
  required:
    - field

2. Add endpoint to paths section:

/path/{param}:
  get:
    operationId: operation_id
    parameters:
    - description: Parameter description
      in: path
      name: param
      required: true
      schema:
        type: string
    responses:
      "200":
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResponseSchema'
        description: Success description
      "404":
        description: Not found description
    summary: Brief summary
    tags:
    - service

Nullable fields in OpenAPI 3.0: For fields that can be null, use the nullable property:

optional_field:
  type: string
  description: This field can be null
  nullable: true

Step 6: Generate Unit Tests

Create comprehensive unit tests in tests/api/test_<view_file>.py:

Test conventions:

• Use context manager form of mocking (with mock.patch(...) as mock_name:)
• Always use autospec=True for patches
• Use spec=ClassName for Mock objects that represent class instances
• Test success case (200 response)
• Test all error cases (404, 500, etc.)
• Use descriptive test names: test_<function_name>_<scenario>
• Use descriptive docstrings

Test template:

def test_endpoint_name_success():
    """Test successful response."""
    with mock.patch(
        "paasta_tools.api.views.<module>.<function>", autospec=True
    ) as mock_function:
        mock_function.return_value = "expected_value"

        request = testing.DummyRequest()
        request.swagger_data = {"param": "value"}

        response = endpoint_function(request)
        assert response.status_code == 200
        assert response.json_body == {"key": "expected_value"}


def test_endpoint_name_not_found():
    """Test 404 when resource not found."""
    with mock.patch(
        "paasta_tools.api.views.<module>.<function>", autospec=True
    ) as mock_function:
        mock_function.side_effect = SomeException("not found")

        request = testing.DummyRequest()
        request.swagger_data = {"param": "value"}

        with pytest.raises(ApiFailure) as exc_info:
            endpoint_function(request)
        assert exc_info.value.msg == "not found"
        assert exc_info.value.err == 404

Step 7: Generate OpenAPI Client Code

Run the code generator:

make openapi-codegen

This regenerates the Python client code in paasta_tools/paastaapi/ based on the updated oapi.yaml.

Step 8: Run Tests and Validation

1. Run the new tests:

.tox/py310-linux/bin/pytest tests/api/test_<view_file>.py::<test_name> -xvs

2. Run mypy type checking:

.tox/py310-linux/bin/mypy paasta_tools/api/views/<view_file>.py
.tox/py310-linux/bin/mypy tests/api/test_<view_file>.py

3. Run pre-commit checks:

.tox/py310-linux/bin/pre-commit run --files paasta_tools/api/views/<view_file>.py tests/api/test_<view_file>.py paasta_tools/api/api.py paasta_tools/api/api_docs/swagger.json paasta_tools/api/api_docs/oapi.yaml

4. Stage the generated files:

git add paasta_tools/paastaapi/

Step 9: Summary

Provide a summary of:

• Files created/modified
• Endpoint URL and method
• Test coverage (number of tests added)
• Any manual steps needed

Example Reference

See the container image endpoint implementation as a reference:

• View: paasta_tools/api/views/service.py:43-63
• Route: paasta_tools/api/api.py:166-169
• Tests: tests/api/test_service.py:63-143

Common Patterns

Error Handling

• NoDeploymentsAvailable → 404
• KeyError for missing config fields → 500
• ValueError for invalid input → 400
• Generic exceptions → 500

Response Patterns

• Single value: {"field_name": "value"}
• List: {"items": [...]}
• Complex object: Use TypedDict schema

Utility Functions

Common utilities are usually found in paasta_tools/utils.py

Notes

• Atomic commits: Each endpoint should be a single, self-contained commit
• Bisectable history: All tests must pass after adding the endpoint
• Type safety: Use type hints and ensure mypy passes
• Documentation: Keep Swagger and OpenAPI docs in sync
• Testing: Aim for 100% coverage of the new endpoint

Skill Exit

After completing all steps successfully, provide the user with:

1. Summary of changes
2. Test results
3. Verification that pre-commit checks pass
4. Suggested commit message following PaaSTA conventions