ワンクリックで
paasta-api-endpoint
Automates the creation of new PaaSTA API endpoints following established patterns
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
メニュー
Automates the creation of new PaaSTA API endpoints following established patterns
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
SOC 職業分類に基づく
| 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 |
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.
/paasta-api-endpoint
This skill will:
paasta_tools/api/views/paasta_tools/api/api.pyswagger.jsonoapi.yamlUse this skill when you need to:
When this skill is invoked, follow these steps:
Ask the user the following questions (use AskUserQuestion tool for better UX):
/v1/services/{service}/instances/{instance}/status){"status": "running", "count": 5})service.py, instance.py, autoscaler.py, etc.paasta_tools/utils.py will be used?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:
Response from pyramid.response for explicit status codesApiFailure from paasta_tools.api.views.exception for error handlingsettings.soa_dir to get the SOA configuration directoryAdd 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).
Update paasta_tools/api/api_docs/swagger.json:
"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"
}
]
}
}
"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
}
Update paasta_tools/api/api_docs/oapi.yaml:
components/schemas section:ResponseSchema:
description: Schema description
type: object
properties:
field:
type: string
description: Field description
required:
- field
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
Create comprehensive unit tests in tests/api/test_<view_file>.py:
Test conventions:
with mock.patch(...) as mock_name:)autospec=True for patchesspec=ClassName for Mock objects that represent class instancestest_<function_name>_<scenario>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
Run the code generator:
make openapi-codegen
This regenerates the Python client code in paasta_tools/paastaapi/ based on the updated oapi.yaml.
.tox/py310-linux/bin/pytest tests/api/test_<view_file>.py::<test_name> -xvs
.tox/py310-linux/bin/mypy paasta_tools/api/views/<view_file>.py
.tox/py310-linux/bin/mypy tests/api/test_<view_file>.py
.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
git add paasta_tools/paastaapi/
Provide a summary of:
See the container image endpoint implementation as a reference:
paasta_tools/api/views/service.py:43-63paasta_tools/api/api.py:166-169tests/api/test_service.py:63-143NoDeploymentsAvailable → 404KeyError for missing config fields → 500ValueError for invalid input → 400{"field_name": "value"}{"items": [...]}Common utilities are usually found in paasta_tools/utils.py
After completing all steps successfully, provide the user with: