Skip to content
Module
Module 6 of 6Lesson 1 of 2~17 min

Writing your product's integration spec

An integration deserves its own spec, more precise than a standard user story. This lesson walks you through writing the one for your product, with the data mapping and production monitoring, linked to the collection you have tested. Your engineers can then estimate it without back-and-forth.

Take this lesson: your first course is freeSee the full syllabus

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

Topics covered

  • integration spec
  • functional specification
  • data mapping
  • production monitoring

Where it fits

Writing the integration spec

How do I bring all of this together in a spec the team can estimate, and apply it to my product?

Lessons in this module

  1. Writing your product's integration spec (this lesson)
  2. Exit kit and application plan

What you will learn in this module

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