APIs for Product Managers: Integration Guide

An API defines how software can use another system’s data or capabilities. For a Product Manager evaluating an integration, the practical task is to connect the intended customer journey with the operations, permissions and behaviour the API actually supports. A provider’s feature list alone rarely answers whether an integration can deliver the experience being planned.

This guide introduces the HTTP API concepts needed to follow that investigation: requests and responses, methods, access controls and the work an integration needs after launch. It uses a hypothetical order-history screen at Mercato, a commerce platform. For a visual overview, start with the API infographic. If the API itself is the product being offered to developers, the separate article on API product management covers adoption, prioritization and lifecycle decisions.

Read a request against a customer requirement

Mercato wants customers to see their recent orders, including the payment state and amount. Its frontend calls a backend operation that can return orders for the authenticated account. In an HTTP API, the endpoint is the address at which an operation is exposed; the method indicates how the request is intended to interact with that resource. Query parameters can refine the request, for example by limiting the number of results.

The following request and JSON response are illustrative, not a live endpoint. JSON organizes data into named fields and values. Here, the response contains one order and a cursor for continuing through the results:

GET /orders?limit=20

{
  "orders": [
    {"id": "ord_8421", "status": "paid", "total": 49.90, "currency": "EUR"}
  ],
  "next_cursor": "page_2"
}

To turn that response into a requirement, the team needs to know what “paid” means, whether the amount includes delivery and how currency and units are represented. In this example the amount is expressed in euros; another provider might use minor units or a different representation. The interface should use the documented contract rather than infer those meanings from a sample value.

The next-page cursor also changes the work. If only the first response is retrieved, older orders could appear to be missing. GitHub’s REST API provides a real example of pagination, using response links to find additional pages. Providers choose different pagination mechanisms, so the team must check the actual documentation and what happens when the underlying data changes between requests.

Recognize what an operation is intended to do

The method and endpoint need to be read together. An API might expose order retrieval and refund creation as separate operations with different permissions. The same HTTP method can appear across many resources, and the provider defines which operations are available.

Common methods in HTTP APIs
Method	Meaning to check in the API contract
GET	Retrieve a representation, such as the current order state.
POST	Submit data for processing; creating a payment is one possible use.
PUT	Create or replace the state of the resource at the target address.
PATCH	Apply a partial modification to a resource.
DELETE	Request removal of the target resource. Check the provider’s rules for data retention and permanent deletion.

A response combines a status code with headers and, where applicable, a body. Headers carry metadata such as content type, pagination links or access credentials on a request. The body may hold the requested records, an operation’s current state or structured error information. A successful HTTP response confirms the outcome described by that endpoint; it does not necessarily mean that an entire business process has finished.

For Mercato, a request could be accepted while a payment remains pending. Its order-history screen needs to represent that state accurately. If the API omits a field the design needs, the team has to change the requirement, find another source or extend the API before promising that information to customers.

Establish whose data the integration may use

Authentication establishes the identity or credentials presented by a caller; authorization determines the permitted actions and resources. Being able to call an API does not mean being allowed to read every customer’s orders. Mercato’s backend must apply account-level rules, including when somebody changes an order identifier in a request.

Private API keys and OAuth access tokens appear frequently in integration documentation, but their capabilities depend on the provider. OAuth is an authorization framework and can support delegated or application-only access. The API keys vs. OAuth comparison develops the consequences for permissions, credential renewal and disconnection. The shorter authentication vs. authorization explanation separates identity from allowed actions.

Translate failures into a customer experience

Failure handling starts with understanding what the response says. A 401 response concerns missing or invalid authentication credentials; 403 indicates that the server refuses the request. A 429 response signals too many requests under the service’s rules, while a 500 response reports an unexpected server condition. The error body and the provider’s documentation give the context needed to decide what the application should do.

On Mercato’s order-history screen, unavailable data must not be presented as proof that the customer has never placed an order. The team can distinguish a loading failure from an empty result and decide whether previously retrieved information can still be shown with an appropriate indication of freshness. That decision depends on the data and its consequences; an outdated delivery estimate and an uncertain payment state need different treatment.

A timeout creates another case: the calling system has stopped waiting without necessarily knowing whether the receiver acted. Automatically retrying a request that creates a payment requires different safeguards from retrying a read. The webhooks and polling article follows an uncertain payment through updates, duplicate handling and recovery.

Plan beyond the first successful response

An integration keeps consuming capacity after launch. Pagination, repeated checks and recovery work can multiply requests. The rate limits guide explains how provider limits affect that traffic. Cost estimates should use the expected request pattern and the supplier’s billing model, rather than assume one API call per customer action.

Updates can arrive through scheduled API queries or event notifications. A webhook may tell Mercato that an order’s state has changed, while an API query retrieves details. The right combination depends on acceptable delay and recovery requirements. These are parts of one integration, not mutually exclusive technologies.

API contracts also evolve. A provider may change an operation, add fields or retire a version. Version identifiers can appear in headers or URLs, but the identifier alone does not explain compatibility or support periods. Assign someone to track change notices, evaluate the effect on the integration and reserve capacity for required migrations. The GitHub versioning documentation illustrates how one provider communicates these policies.

Turn the API review into an integration brief

A useful brief records the customer behaviour and the evidence supporting it. Engineering can then investigate the relevant operations and their limitations, while Product can adjust scope before those limitations become a launch problem. For Mercato’s order-history feature, the review would cover:

Which account’s orders are returned, and how access is restricted to that account.
Whether the available fields cover the intended screen, including payment state, amounts and delivery information.
How additional pages are retrieved and how current the displayed information needs to be.
What the customer sees during an error, a delay or an uncertain outcome.
Which usage limits and charges apply to normal operation and recovery.
Who monitors the integration, handles support incidents and tracks provider changes.

Documentation can describe the contract, and a sandbox or controlled test can help check an assumption. Neither replaces a review of production conditions and relevant edge cases. When the team publishes its own HTTP API, an OpenAPI description can record operations and schemas in a structured format; it does not demonstrate that the running service meets every requirement.

For a broader view of the components involved, follow the annotated checkout architecture diagram. If the immediate decision is whether to offer and invest in an API as a product, continue with API product management. The book APIs for Product Managers develops the technical concepts and integration decisions introduced here.