메뉴
Automates the creation of new PaaSTA API endpoints following established patterns
기본적으로 소스를 먼저 확인하는 Prompt가 선택됩니다. 직접 명령으로 전환하거나 로컬 사본을 다운로드할 수도 있습니다.
설치 여부를 결정하기 전에 SKILL.md와 SkillsMP에 표시된 보조 파일을 읽어 보세요.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
직접 명령은 검토 Prompt를 거치지 않습니다. 실행하기 전에 소스를 확인하세요.
npx skills add https://github.com/Yelp/paasta --skill paasta-api-endpoint명령은 한 줄로 유지됩니다. 복사하기 전에 가로로 스크롤해 전체 내용을 확인하세요.
로컬 사본을 원하시나요? SkillsMP에서 현재 제공할 수 있는 파일을 다운로드하세요.
SKILL.md 표시 중
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: