Six Techniques for API Pagination
When a client requests a large collection from an API, the server should return a manageable portion and tell the client how…
For developers building services in 2026, an API is the set of rules that lets one piece of software request data or actions from another. AI agents, software that uses AI to choose and carry out tasks, and automated workflows now use APIs alongside people and conventional applications. That shift makes clear instructions, narrow permissions, and reliable checks more important: an agent needs to know what an operation does, while the service still needs to verify what the caller is allowed to do.
Design APIs with clear contracts, check permissions for each piece of data and each action, and run automated checks before deployment. An API contract describes its operations, inputs, outputs, and expected behavior. A well-maintained contract helps developers and tools understand an API, but it does not guarantee that the implementation is secure or that an AI agent will use it correctly.
AI agents choose and invoke operations based on the information available to them. Vague names, incomplete input descriptions, and unclear error responses leave more room for incorrect calls. Names that follow a consistent pattern, complete descriptions of fields, clear authentication requirements, and documented side effects help people and software use an API reliably.
In Postman’s 2025 survey of more than 5,700 developers, architects, and executives, 89% of respondents said they used generative AI in their work, while 24% said they actively designed APIs with AI agents in mind. Those figures describe survey respondents, not every API developer, but they show that broad AI use has not yet translated into equally widespread agent-focused API design. For pagination patterns that agents can follow more easily, see normalizing API pagination.
The OpenAPI Specification provides a machine-readable way to describe HTTP APIs. Tools can use an OpenAPI document to produce documentation. They can also produce client and server code, as well as tests. When the document matches the deployed service, consumers have less to guess about, and automated checks can compare the service with the same description. The OpenAPI 3.2 specification also describes sequential and streaming media types, including how to describe individual items in a stream. Before adopting newer specification features, check that the tools in your development environment support the version you plan to use.
A description alone cannot enforce permissions or business rules. For example, an API contract can document that a request includes a record identifier, but the server must still confirm that the caller may access that particular record. Treat the contract as an aid to understanding and testing, then verify behavior against the running service.
The Model Context Protocol, or MCP, is a standard way for AI-capable clients to discover and invoke tools that connect to data and services. Postman’s 2025 survey found that 70% of respondents were aware of MCP, while 10% said they used it regularly. Awareness therefore should not be mistaken for widespread production use.
MCP and API design address different layers. An API defines the available operations, data, permissions, and behavior. A tool protocol such as MCP gives an agent-capable client a standard way to discover and call tools. An MCP server can expose or mediate API operations, but the underlying service still needs to check authorization and enforce its business rules. The MCP specification update from July 2026 describes a stateless protocol core, in which requests carry the information needed to handle them across server instances. That design supports deployment flexibility; it does not grant a caller access to protected data.
When exposing operations to agents, make each operation’s effect clear. Separate read actions from actions that change data, document meaningful side effects, and make the service return typed errors that distinguish invalid input from denied access. Keep credentials in trusted execution components rather than in prompts or other model-visible content. These choices help the agent select an operation while keeping the service responsible for deciding whether the request is allowed.
Authentication identifies the caller. Authorization determines what that caller may access or change. A valid login or token does not show that the caller has permission to retrieve a specific record or perform a specific action.
OWASP’s API Security Top 10 highlights broken object-level authorization as a recurring risk. It occurs when a server accepts a record identifier without checking whether the caller has access to that specific record. For example, a user who changes an identifier in a request should not receive another user’s data simply because the server recognized the user’s account. Check access at the object and operation level, including for requests that arrive through internal services or AI tools. The OWASP API Security Top 10 also covers risks such as broken authentication, excessive resource consumption, and poor API inventory management.
NIST’s 2025 API protection guidance applies zero-trust principles to APIs, including internal ones. In this context, zero trust means a service does not treat a request as safe just because it came from inside an organization’s network. The service validates the caller, checks permissions, validates request and response data, and limits resource use. Rate limits restrict how quickly a caller can make requests; quotas typically govern longer-term usage or billing. A monthly quota alone does not prevent a caller from overwhelming a service in a short period. See NIST’s API protection guidance for controls across the API lifecycle.
Inventory also needs to show what APIs expose, not just how many exist. In Akamai’s 2026 study, 87% of surveyed organizations reported at least one API-related security incident in the prior 12 months. Among respondents whose organizations had reported an incident, 42% said an incident involved APIs linked to AI applications, agents, or large language models. The study does not establish that AI caused those incidents. It does show why organizations should track which APIs return sensitive data and which callers can reach them. Only 23% of enterprises reporting a full API inventory said they knew which APIs returned sensitive data, according to the same study. Read the Akamai API security study with those survey limits in mind.
A continuous integration and continuous delivery pipeline, or CI/CD pipeline, automatically checks code and moves it through stages such as testing and release. A CI/CD pipeline can automate deployment, but that alone does not show that an API remains compatible or that its authorization rules work. Postman’s 2025 survey reported that 75% of respondents used CI/CD, while 17% reported contract testing. Contract testing checks whether a service’s actual requests and responses match the expectations described by its consumers or API contract.
A practical pipeline keeps the API specification in version control, validates proposed changes, and compares each change with the previous contract. It then runs functional and integration tests, including checks that verify callers cannot access records or actions outside their permissions. When a change could break existing consumers, the release owner can choose how to handle it: preserve the old behavior, introduce a versioned change, or provide a deprecation period. Generate documentation or client code from the contract when that reduces manual duplication, but review generated changes before release.
Operators also need to monitor the API after deployment. Operators can spot unexpected behavior after deployment by tracking errors, response times, usage patterns, and denied requests. Apply request-size and timeout limits to internal callers as well as external ones. Apply concurrency and rate limits to those callers too. These controls address different failure modes: a contract test catches a mismatch before release, while a resource limit constrains what a live caller can consume.
Give Vroni a GitHub issue, bug report, spec, or rough idea. It reads the repo, plans the change, writes code, runs checks, and works toward a review-ready pull request.
Take a look at vroni.com