--- 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: ```python @view_config(route_name="", request_method="", renderer="json") def (request): """.""" # 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`: ```python config.add_route( "", "", ) ``` 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: ```json "/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: ```json "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: ```json "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: ```yaml ResponseSchema: description: Schema description type: object properties: field: type: string description: Field description required: - field ``` 2. Add endpoint to `paths` section: ```yaml /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: ```yaml 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_.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__` - Use descriptive docstrings **Test template:** ```python def test_endpoint_name_success(): """Test successful response.""" with mock.patch( "paasta_tools.api.views..", 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..", 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: ```bash 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: ```bash .tox/py310-linux/bin/pytest tests/api/test_.py:: -xvs ``` 2. Run mypy type checking: ```bash .tox/py310-linux/bin/mypy paasta_tools/api/views/.py .tox/py310-linux/bin/mypy tests/api/test_.py ``` 3. Run pre-commit checks: ```bash .tox/py310-linux/bin/pre-commit run --files paasta_tools/api/views/.py tests/api/test_.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: ```bash 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

paasta-api-endpoint

Scan your own AI components