| name | python-api-sdk |
| description | Update the Python API SDK. Use this skill when the user asks to update the Python API SDK, based on the OpenAPI schema. |
| user-invocable | true |
| allowed-tools | ["read_file","write_file","search_replace","grep","bash","ask_user_question","task"] |
Python API SDK Skill
This skill is a complete cookbook for updating the Python API SDK. It is designed to be used when the user asks to update the Python API SDK, based on the OpenAPI schema.
Step 1: Download the OpenAPI Schema
Start by downloading a fresh OpenAPI schema from https://api.polar.sh/openapi.json. This schema will be the basis for generating the API SDK.
curl -o openapi.json https://api.polar.sh/openapi.json
Step 2: Update the generated types
We have an automatic generator that converts the OpenAPI components and query parameters into proper Python TypedDict. Before generating the API endpoints, make sure to run this generator to update the types based on the latest OpenAPI schema.
just generate-python
Step 3: Identify the Groups of Endpoints
The OpenAPI schema contains a property x-speakeasy-group that categorizes endpoints into groups. This property is used to organize the endpoints in the SDK.
Use jq to identify all the groups in the OpenAPI schema.
jq '.paths | to_entries[] | .value[].["x-speakeasy-group"]' openapi.json | sort | uniq
Step 4: Generate the API SDK Groups using the python-api-sdk-group skill
For each group identified in the previous step, generate the API SDK group. For this, load the skill python-api-sdk-group and follow the steps in the skill, and only those steps.
Repeat this process for each group identified in the OpenAPI schema.
You can use subagents to run the skill for each group in parallel. Instruct the subagents to follow closely the steps in the python-api-sdk-group skill, and only those steps.
Step 5: Format, lint and typecheck
After generating or updating the SDK, make sure to format, lint and typecheck the code to ensure that it adheres to the project's coding standards and is free of errors.
just lint
This will run the linter and type checker on the codebase. Make sure to fix any issues that are reported before considering the task complete.
Done
Once done, your task is done. No need to make follow-up testing or checks. End here and report back.
