Reading a REST API's documentation

Lesson 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.

Where it fits

Reading an API

How do I read an API's documentation and understand what it answers, including when things fail?

Lessons in this module

1. Reading a REST API's documentation (this lesson)
2. Status codes, errors and product decisions

What you will learn in the course

This lesson is part of the course Design and test an API integration as a PM

• 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.

Related courses

• Git for PMs: ship as a team without putting production at riskAdvanced · ~3 hr 30 min
• Explain how a web product works, from browser to serverAll levels · ~2 hr 30 min
• Model your product’s data and query it with SQLJunior · ~3 hr 30 min