List view
Goal: To explain how to navigate large datasets. see for example :https://docs.stripe.com/api/pagination https://docs.github.com/en/rest/using-the-rest-api/using-pagination-in-the-rest-api?apiVersion=2022-11-28 Swagger lists the parameters (page, limit), but it rarely explains the logic. Explain: Is it cursor-based or offset-based? Example: Show a code snippet of a loop handling 1,000 items across 10 pages. We need this kind of info : The Style: Which pagination method are we using? - Offset/Page based? (Easier for humans: page=2) - Cursor-based? (Better for performance: cursor=ey...) Parameter Names: What exact query parameters should the user send? (e.g., limit, offset, per_page, page, starting_after) Defaults: If the user doesn't specify a limit, how many items do we return by default? (e.g., 20 items). Maximums: What is the hard limit a user can request in one go? (e.g., "Max 100 items per page"). Filtering Syntax: How do users filter data? - Simple: ?status=active - Complex: ?q=status:active+created:>2023-01-01
No due dateTo prevent users from accidentally breaking their integration by hitting limits. Limits: How many requests per second/minute? Headers: Do we send X-RateLimit-Remaining headers? Document them so scripts can handle back-off automatically. To write this article, please provide: The Hard Numbers: What are the limits? - Requests per Second (RPS)? - Requests per Minute? - Requests per Day? The Scope: Is the limit applied per IP address or per API Token? (This is crucial for developers designing their architecture). Response Headers: When a user makes a call, do we return headers telling them how many calls they have left? - Example: X-RateLimit-Remaining: 49 The "Cooldown": If they hit the limit (Error 429), how do they know when they can try again? Do we send a Retry-After header?
No due dateDon't just list generic HTTP 404/500 codes. Map them to your business logic: What does a 422 Unprocessable Entity mean for Sekoia? Troubleshooting: "If you see Error X, check Y." See : https://www.twilio.com/docs/api/errors https://docs.stripe.com/error-handling The JSON Error Body: When the API fails, what does the JSON response look like exactly? Please provide a sample. Look for fields like: error_code, message, details, trace_id. Business Logic Mapping: We know 404 means "Not Found," but what triggers it in our system? (e.g., "ID does not exist" vs "ID exists but belongs to another user"). Specific Error Codes: Do we have an internal list of custom error codes (e.g., ERR_1001)? If so, I need the list and their definitions. Validation Errors: If I send a bad input (e.g., email address without an @), how does the API report that specific field error? For each error, please provide code / Description / Possible cause / Possible solutions
No due dateSwagger/Open API shows where the key goes (header/query), but not how to get it. In this article we will : Explain: How to generate API keys in our dashboard. Security: Best practices (e.g., "Don't commit keys to GitHub," "How to rotate keys"). Scopes: If we have permissions (Read-only vs. Admin), explain them here. See for example :https://docs.github.com/en/rest/authentication/authenticating-to-the-rest-api?apiVersion=2022-11-28. https://docs.stripe.com/api/authentication I need these kind of information to be included in the article : The Mechanism: specifically what standard are we using? (e.g., Basic Auth, Bearer Token, API Key, OAuth2 Client Credentials). Location: Where exactly does the key go? Header? (e.g., Authorization: Bearer <key>) Query Parameter? (e.g., ?api_key=<key>) Token Lifespan: Do tokens expire? If so, how long do they last (1 hour, 30 days, forever)? Key Rotation: If a user suspects a breach, how do they revoke a key? Is there an API endpoint for that, or must they use the Dashboard? Permissions (Scopes): Do keys have different levels (e.g., read-only vs admin)? If so, please list the available scope strings.
No due dateThis is the most important article. Our goal: Time to First Call (TTFC) under 5 minutes. Content: A linear, step-by-step guide to making the simplest possible successful API call. Format: Prerequisite (Get API Key) > Install Request Library > Copy Code >Run >See "200 OK". What we wont do: Explain architecture here. Just get them a win. See for example : https://docs.stripe.com/get-started/api-request -> The "Golden Path" Endpoint: What is the single simplest GET request a user can make to see data? (e.g., GET /users/me or GET /server-status). Base URLs: What is the exact URL for Production vs. Sandbox/Staging? Example: https://api.myapp.com vs https://sandbox-api.myapp.com Prerequisites: Does the user need to create any data in the UI before using the API? (e.g., "Must create a project in the dashboard first"). Test Data: Is there a way to generate "dummy data" so the API isn't empty when they first query it?
No due date