Implementation

Can agents actually build and execute with your API?

Understanding an API is not the same as being able to use it. Implementation covers the execution surfaces and interaction patterns that determine whether agents can actually construct valid requests, handle responses correctly, and compose multi-step workflows. This is where API design meets the reality of automated execution.

Key principles

  • Offer multiple execution surfaces: REST APIs, SDKs, MCP servers, CLI tools
  • Give typed interfaces that constrain invalid inputs at the boundary
  • Design capabilities that are narrow, explicit, and composable
  • Support multi-step workflows with async jobs, polling, and event patterns
  • Use interoperable data formats and standard authentication patterns

Interfaces

Different agents operate through different execution surfaces. Each provides different levels of type safety and guardrails.

Execution surfaces compared

SDKs - strong types prevent agents from constructing invalid requests in the first place

MCP servers - structured tool definitions tell the agent exactly what inputs are expected

REST APIs - maximum flexibility but the least guidance

CLI tools - preferred by DevOps and infrastructure agents

Quality matters more than quantity.

A single well-typed SDK is worth more than five poorly documented interface options.

Composability

Real tasks rarely map to a single API call. Agents need to compose multiple operations into workflows: create a resource, wait for it to be ready, configure it, verify the configuration, then proceed.

Design principles

  • Single-purpose endpoints with predictable resource boundaries
  • Explicit side effects so agents can predict what each call will do
  • Narrow, composable capabilities rather than multi-purpose endpoints with complex parameter interactions

Async patterns

Support these patterns for long-running operations. Without them, agents must resort to arbitrary waits and retries:

  • Job and request IDs
  • Polling endpoints
  • Cancellation support
  • Webhooks and event streams

Interoperability

Agents often work across multiple APIs in a single workflow. Interoperability determines how smoothly your API plays with others.

  • JSON schemas and well-defined response structures that other systems can consume without transformation
  • Standard authentication patterns that agents can manage programmatically
  • Widely adopted formats - ISO 8601 dates, standard HTTP status codes, RESTful conventions

When your API follows common conventions, agents can apply general knowledge rather than learning API-specific quirks.