thinkhard.SI

Prompt repository Engineering & code

Brief a coding agent to integrate a third-party API

You want a coding agent to connect your code to an outside API properly, with tests that never call the real service.

Registry no.
ENG-035
Collection
Engineering & code
Laid out for
Coding agent
Score
10 out of 10
Blanks to fill
12
Added

Engineering & codeCode agent

The prompt

Score 10 of 10, Excellent

Use it when You want a coding agent to connect your code to an outside API properly, with tests that never call the real service.

  • {{api_name}}
  • {{client_path}}
  • {{use_case}}
  • {{api_docs}}
  • {{auth_method}}
  • {{env_vars}}
  • {{rate_limits}}
  • {{pattern_file}}
  • {{test_command}}
  • {{max_retries}}
  • {{off_limits}}
  • {{docs_file}}
Full prompt and why it works
Prompt
Goal: Add a client for the {{api_name}} API at {{client_path}} (for example src/clients/), and use it to {{use_case}}, so that the rest of our code calls one tested module instead of making raw HTTP requests.

Context:
- The endpoints we need, with the official documentation for each (links or pasted sections):
"""
{{api_docs}}
"""
- Authentication method: {{auth_method}}
- Environment variable names for credentials and settings: {{env_vars}}
- Rate limits, from the documentation: {{rate_limits}}
- An existing client or HTTP module in this repository to use as the pattern: {{pattern_file}}
- Test command: {{test_command}}

Constraints:
- Read credentials only from the environment variables above. Never hard-code, log or commit them, and add the names to .env.example with empty values.
- Base every request and response shape on the documentation above, not on memory, because APIs change. If an endpoint we need is not covered, stop and ask for its documentation.
- Set a timeout on every request. Retry with exponential backoff and jitter, at most {{max_retries}} times, only for network errors, 429 and 5xx responses, and only for requests that are safe to repeat; honor a Retry-After header. Do not retry other 4xx responses.
- Turn failures into our own error types carrying the status code and the API's request ID, with no credentials or full request bodies in the message.
- Handle pagination if an endpoint pages its results, and validate the fields we use from each response.
- Use the HTTP library the pattern file uses. Do not add dependencies without asking. Do not touch {{off_limits}}.
- Tests must not call the real API. Mock HTTP at the boundary with the tool the repository already uses, and cover success, 401, 404, 429 with Retry-After, a 500 followed by success, a timeout, a malformed response and a second page of results.
- Write a short usage section in {{docs_file}}: setup, the environment variables, one example call, and the errors callers should handle.

Done when:
- {{test_command}} passes with the new tests, and the linter and type checker pass.
- A search of the diff finds no credential values, and .env.example lists the new variables.

Verify: run the tests, read the output and iterate until they pass. Then report in this format: Files changed, Client functions, Retry rules as built, Commands run with the last 20 lines of their output, and To test by hand against the provider's sandbox, if it has one. Do not send any request to the live API yourself.

Variables

{{api_name}}
The service, for example "the shipping carrier's rates" or "the payments provider".
{{client_path}}
Where the client module goes, for example src/clients/shipping.ts.
{{use_case}}
What our code needs from it, for example "fetch live shipping rates at checkout".
{{api_docs}}
Links to, or pasted sections of, the official docs for each endpoint you need, including request and response examples.
{{auth_method}}
For example "API key in an Authorization header" or "OAuth client credentials".
{{env_vars}}
The variable names to use, for example SHIPPING_API_KEY and SHIPPING_API_BASE_URL.
{{rate_limits}}
What the docs say, for example "100 requests per minute per key", or "not documented".
{{pattern_file}}
An existing client to copy for structure and HTTP library, for example src/clients/email.ts.
{{test_command}}
For example npm test or pytest.
{{max_retries}}
The most retries allowed, for example 3.
{{off_limits}}
Files or systems that must not change, for example the checkout flow itself.
{{docs_file}}
Where the usage notes go, for example README.md or docs/integrations.md.

Why it works

  • What to avoid. Credentials come only from the environment and tests never touch the real API, so neither a key nor live traffic can leak from the work.
  • Background facts. Request and response shapes come from the documentation you paste, not the agent's memory of an API that may have changed.
  • What good looks like. Tests cover the failures that matter in production, from 429 with Retry-After to malformed responses, and the diff is searched for credential values before the work counts as done.

How to use it

  1. Press Fill in blanks and type your details into each blank. What you type stays in this browser.
  2. Copy the filled prompt into the AI tool you already use, such as ChatGPT, Claude or Gemini, or open it in the Grader or the Prompt Tester here.
  3. Before you rely on it, try it on three or four real examples. The Prompt Tester runs them all at once and shows which ones go wrong.
Use it from code

Get this prompt as JSON from the free REST API, with your own text in the blanks, or let an AI assistant fetch it through the MCP server. No key.

curl -s https://thinkhard.si/api/v1/prompts/coding-agent-third-party-api

With the MCP server added to Claude, ChatGPT, Cursor or VS Code, call get_prompt with {"prompt": "coding-agent-third-party-api"}, or just ask for it by name.