Design and test an API integration as a PM
Read an API’s docs, test it yourself in Bruno or Postman, and write an integration spec developers can estimate.
Read an API's documentation, test it yourself in Postman or Bruno, then write an integration spec that developers can estimate without guessing: flows and data, authentication and secrets, errors and retries, pagination and rate limits, webhooks and idempotency, environments and versions. You leave with an integration spec and a collection of tested requests, on an API your product uses or is about to use.
What you will be able to do
- Read a REST API's documentation (resources, endpoints, methods, parameters, JSON bodies, OpenAPI description) and extract what the integration needs.
- Send, save and test requests in Postman or Bruno (collection, environments, variables, assertions) to check an API's real behavior.
- Interpret status codes and error responses, and decide the product behavior (fix, retry, alert, inform the user).
- Choose and specify the authentication method (API key, token, OAuth 2.0), the minimal permissions and the rules for managing secrets.
- Specify pagination, rate-limit handling, webhooks and idempotency for an integration that withstands volumes, outages and duplicates.
- Plan environments (sandbox, production), versions, breaking changes and deprecations in the spec and the test plan.
- Write a complete integration spec, with a collection of tested requests, ready to be estimated by the team.
Prerequisites
- Know what an HTTP request, a status code, a frontend, a backend and an API are, at the level of the course "Explain how a web product works"
- Be able to install Bruno, a free desktop application with no account, or, failing that, create a free Postman account
- Have in mind a real or planned integration for your product (payment, CRM, invoicing, messaging, AI…), with access to its public documentation
- No code to write: a few lines of tests are provided ready to copy, and every terminal command has an equivalent in the interface.
- Explain how a web product works, from browser to server
Syllabus
What will I be able to design and test by the end of this course, and in what order?
- Course overview2 steps
Objective · By the end of this overview, you will know what you will be able to do (test an API yourself and specify its integration), the two deliverables you will produce on your own product and which five modules get you there.
How do I read an API's documentation and understand what it answers, including when things fail?
Objective · By the end of this lesson, you will be able to read a REST API's documentation (resources, endpoints, methods, parameters, JSON bodies, OpenAPI description) and extract, for a given flow, the calls needed, the required fields and the questions to ask the publisher.
Objective · By the end of this lesson, you will be able to interpret an API's status codes and error responses, tell errors to fix from errors to retry, and match each one with a product behavior (message, retry, alert).
How can I check an API's real behavior myself, without writing code?
Objective · By the end of this lesson, you will be able to install an API client (Postman or Bruno), create a collection and an environment with variables, send GET and POST requests with headers and a JSON body, and read the response you get.
Objective · By the end of this lesson, you will be able to add tests to your requests, reuse a value from a response in the next request, organize a collection that also covers failure cases and replay it in one click.
Who may call the API, to do what, and how do you avoid the most common flaws?
Objective · By the end of this lesson, you will be able to choose the authentication method suited to an integration (API key, token, OAuth 2.0 and its flow), specify the minimal scopes and the connection journey, and write the rules for managing secrets.
Objective · By the end of this lesson, you will be able to spot in an integration the most frequent risks of the OWASP API Security Top 10 (access to someone else's object, excess data exposed, unrestricted consumption, blind trust in a third-party API) and write the matching security criteria in the spec.
How does the integration withstand large volumes, limits, outages, duplicates and new versions?
- Pagination and rate limits5 steps
Objective · By the end of this lesson, you will be able to read how an API paginates its lists and limits the number of requests, estimate the number of calls and the duration of a synchronization, and specify the integration's behavior when a limit is reached.
Objective · By the end of this lesson, you will be able to specify how webhooks are received (signature check, fast response, duplicates, ordering, catch-up) and how writes are safely retried thanks to idempotency, so that no event is lost or handled twice.
Objective · By the end of this lesson, you will be able to plan in a spec the move from sandbox to production, the choice and pinning of an API version, the distinction between breaking and compatible changes, and the monitoring of deprecations.
How do I bring all of this together in a spec the team can estimate, and apply it to my product?
Objective · By the end of this lesson, you will be able to write your product's integration spec in ten sections, with its data mapping table and its monitoring plan, and link it to your collection of tested requests.
Objective · By the end of this lesson, you will have the course's templates, checklists and prompts (spec, data mapping, error table, review with the team), and you will have planned how to apply them to your integration over 7 and 30 days.