Software projects
Prepare questions before integrating an API
Before writing integration code, turn what you need from the API into questions and answer each from the current official documentation. Record the source beside every answer. Anything the documentation does not state becomes an open question with a small test.
A text to start with
I plan to integrate [API name] to [what my software needs to do]. Here are the documentation pages I'm using: [links or pasted text]. List questions about authentication, rate limits, error responses, pagination, versioning and data handling that my requirements raise. For each, show what the pasted documentation says, or mark it unanswered. Suggest a test for every unanswered item.
Example request. Change the details to fit your situation.API integration question list
API and version: [ ] What my software needs from it: [ ] Requirement: [ ] Documented behavior: [ ] Source page and date read: [ ] Unanswered question: [ ] Test to run: [ ] Test result: [ ] Authentication method documented: [ ] Rate limits or quotas documented: [ ] Error responses documented: [ ] Pricing page checked on: [ ] Questions to send to the provider: [ ] Answers that came from unofficial sources: [ ]
Behavior the documentation doesn't state
An example request shows one successful call. It does not show how the endpoint behaves with missing fields, large result sets or repeated requests. Read pricing, quotas and limits from the provider's current pages and note the date you read them, since they can change. Check that the documentation you pasted matches the version you will call. Flag any answer that came from a blog post or forum reply instead of official documentation, and keep it separate from the confirmed list.
Ask another agent to check the result
Check this list for any statement about endpoint behavior, pricing or limits that was inferred from an example request instead of stated in the documentation. Mark each one as unconfirmed, name the missing source and suggest a test that would settle it.
Test the open questions
Pick the unanswered questions that could change your design and test them first, using a sandbox or test account if the provider offers one. Write down the result and the exact request you made. Ask the provider's support channel about anything the tests cannot settle. Update the list as answers arrive, and note the date next to each documented limit.