# Enterprise API development in 2026: API-first design, security and AI agents

> How enterprise APIs are built and run in 2026: API-first contracts, REST, GraphQL or gRPC, versioning, gateways, OWASP API security and AI agents over MCP.

- URL: https://computese.com/the-future-of-enterprise-api-development/
- Author: Duong Quan Nguyen, CEO, Computese
- Published: 2019-07-10
- Updated: 2026-09-25
- Topics: Integrations, Web development

## In short
- Enterprise APIs in 2026 are contract-first: the OpenAPI 3.2 or AsyncAPI 3.1 description is written, reviewed and linted before the code, then drives mocks, SDKs, documentation and tests.
- Choose the style per flow: REST for most partner and public APIs, GraphQL for front ends that assemble many objects, gRPC between internal services, webhooks and event streams to announce changes.
- Broken object level authorization is API1 in the OWASP API Security Top 10 2023. Check ownership in the service on every call that takes an object ID; a gateway cannot do it for you.
- Retire versions in the open: mark operations deprecated in the contract, send the Deprecation (RFC 9745) and Sunset (RFC 8594) headers, and use gateway logs to find who still calls.
- AI agents now call APIs through the Model Context Protocol, a Linux Foundation project since December 2025 whose current spec is 2026-07-28. Give agents narrow scopes, their own rate limits and an audit trail.

Enterprise API development in 2026 starts with the contract. Teams describe each API in OpenAPI, or AsyncAPI for events, lint it against a style guide, then build it, publish it behind a gateway that authenticates, rate-limits and traces every call, and retire old versions with standard Deprecation and Sunset headers. The newest consumer is an AI agent.

This guide is for teams that own APIs other systems depend on: partner and public APIs, internal platforms, and [the integrations between business systems](https://computese.com/system-integration/). It covers what API-first means in practice, how to choose between REST, GraphQL, gRPC, webhooks and event streams, the design conventions integrators notice, versioning and deprecation, gateways, the OWASP API Security Top 10, governance and observability. It ends with where APIs are heading: AI agents as callers, through the Model Context Protocol (MCP), and what that changes for scopes, rate limits and audit.

## What API-first means in practice

API-first means the interface is designed, reviewed and agreed before anyone implements it, and its machine-readable description, the contract, becomes the source of truth. For HTTP APIs that contract is written in the OpenAPI Specification. [OpenAPI 3.2.0](https://spec.openapis.org/oas/v3.2.1.html) was released on September 19, 2025 and the 3.2.1 patch on September 10, 2026, so 3.2.1 is the current version as of September 2026. Its Schema Object is a superset of JSON Schema draft 2020-12, so the schemas in a contract are ordinary JSON Schema. In the terms of the [software development life cycle](https://computese.com/software-and-development/), API-first moves the interface's design phase ahead of everything else and makes its output a file a machine can check.

The order matters: with API-first design, a finished contract lets several teams work at once, from the same file:

- Front-end and partner teams build against a mock server generated from the contract, before the service exists.
- Client SDKs and reference documentation are generated from it, so they match the API by construction.
- Contract tests check that the running service returns what the contract promises; our [automation testing guide](https://computese.com/navigating-the-future-unveiling-10-cutting-edge-automation-testing-trends-of-2024/) covers contract testing and schema checks in the pipeline.
- Reviewers argue about names, resources and error cases in a pull request, when changing them costs nothing.

![An orange contract document in the centre sends arrows to a mock server, a stack of code cards, a documentation page, a test gear and the real service, which all match it.](https://computese.com/images/blog/the-future-of-enterprise-api-development/contract.dc1c8f14e7-1536.webp)

*One reviewed contract feeds the mock, the SDKs, the documentation and the tests, so none of them can drift from the API.*

A contract is short to read. This fragment describes one operation, the scope it needs and the error format it returns:

```yaml
openapi: 3.2.0
info:
  title: Orders API
  version: 2.3.0
paths:
  /orders/{orderId}:
    get:
      operationId: getOrder
      security:
        - oauth: [orders:read]
      parameters:
        - name: orderId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200":
          description: The order
        "404":
          description: No such order, or not one the caller may see
          content:
            application/problem+json:
              schema: { $ref: "#/components/schemas/Problem" }
```

OpenAPI 3.2 also closed gaps that used to push teams outside the contract. It can describe streaming responses such as Server-Sent Events (`text/event-stream`) and JSON Lines, validating each item as it arrives (`itemSchema`); tags can be nested under a `parent`; and a path can define the HTTP QUERY method, which the IETF published as [RFC 10008](https://www.rfc-editor.org/rfc/rfc10008.html) in June 2026. QUERY is safe and idempotent like GET but carries a request body, so complex searches no longer have to be sent as POST.

For message-driven APIs, the contract format is AsyncAPI, which is [protocol-agnostic](https://www.asyncapi.com/docs/reference/specification/v3.1.0): the same description style covers Kafka topics, AMQP queues, MQTT and WebSockets. [AsyncAPI 3.0](https://www.asyncapi.com/blog/release-notes-3.0.0), released in December 2023, separated channels from the operations performed on them so a channel can be reused, and added a request/reply pattern; the current version is 3.1.0. When a task takes several calls in a fixed order (create a customer, then an order, then a payment), the [Arazzo Specification](https://spec.openapis.org/arazzo/latest.html), at version 1.1.0 since May 2026, describes that workflow across OpenAPI and AsyncAPI descriptions in a form both people and software can read.

## REST, GraphQL, gRPC, webhooks or events: choosing an API style

Most enterprises run several API styles, and that is fine. The choice belongs to each flow, not to the company.

| Style                             | Contract                          | On the wire                                           | Fits when                                                                    | Watch for                                                 |
| --------------------------------- | --------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------- |
| REST over HTTP                    | OpenAPI 3.2                       | JSON over HTTP methods and status codes               | Partner and public APIs; business resources any client or script must use    | Chatty clients; versioning discipline                     |
| GraphQL                           | GraphQL schema                    | One endpoint, usually `/graphql`; client picks fields | Front ends that assemble many related objects per screen                     | URL-based caching no longer applies; query depth and cost |
| gRPC                              | Protocol Buffers (`.proto`)       | Binary messages over HTTP/2, streaming both ways      | Internal service-to-service calls across many languages                      | Browsers need gRPC-Web; harder to inspect by hand         |
| Webhooks                          | OpenAPI `webhooks` field          | HTTP POST from the provider to your URL               | Telling a partner something happened, without polling                        | Signatures, retries, duplicates, ordering                 |
| Event streams (Kafka, AMQP, MQTT) | AsyncAPI 3.1                      | Messages through a broker                             | High volume, many consumers, systems that must survive one another's outages | Schema evolution, ordering per key, replay                |
| MCP for AI agents                 | Tool definitions with JSON Schema | JSON-RPC 2.0 over stdio or Streamable HTTP            | Letting AI agents use your systems as tools                                  | Scopes, confirmation for destructive tools, audit         |

**REST over HTTP** stays the default for anything outside your walls because every language, proxy, cache and gateway understands HTTP. [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110.html) defines GET, HEAD, OPTIONS and TRACE as safe, and PUT, DELETE and the safe methods as idempotent. POST is neither, which is why retries of POST need the idempotency keys described below.

**GraphQL** [serves every operation from a single endpoint](https://graphql.org/learn/serving-over-http/), usually `/graphql`, and lets the client ask for exactly the fields it needs; the latest released edition of the specification is dated [September 2025](https://spec.graphql.org/September2025/). That suits web and mobile front ends that assemble many related objects per screen. The trade-off is that objects are no longer identified by URLs, so ordinary HTTP caching stops helping, and one query can ask for a lot, so servers need depth and cost limits.

**gRPC** uses [Protocol Buffers](https://grpc.io/docs/what-is-grpc/introduction/) as both its interface definition language and its message format, and [follows HTTP semantics over HTTP/2](https://grpc.io/docs/what-is-grpc/faq/) while allowing full-duplex streaming. It fits internal calls between services, where both sides are yours and latency matters. Browsers cannot speak it directly; the gRPC-Web project, which the gRPC FAQ lists as generally available, bridges that gap.

**Webhooks** reverse the direction: the provider [calls a URL you registered](https://computese.com/what-is-a-webhook/) when something happens, and OpenAPI has a top-level `webhooks` field to describe those calls. Verify every delivery before trusting it. [GitHub](https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries), for example, signs each payload with an HMAC SHA-256 digest in the `X-Hub-Signature-256` header and tells receivers to compare it in constant time, never with a plain `==`. Then acknowledge quickly, [put the event on a queue and process it idempotently](https://computese.com/dead-letter-queue/), because deliveries can repeat; a small [serverless function](https://computese.com/the-future-of-serverless-computing-streamlining/) that puts each delivery on a queue is one simple receiver.

## Design conventions that save integrators time

Consistency is most of what makes an API pleasant to integrate. A handful of conventions, applied everywhere, do most of the work:

- **One error format.** [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457.html) (July 2023, which obsoletes RFC 7807) defines problem details: a JSON object served as `application/problem+json` with `type`, `title`, `status`, `detail` and `instance`. Clients then parse every error the same way, and so can AI agents.
- **Idempotency keys for POST.** The client sends a unique key with each create or update. [Stripe's API](https://docs.stripe.com/api/idempotent_requests), a well-known example, saves the status code and body of the first request for each key and returns the same result to every retry, even a 500 error, and rejects a reuse of the key with different parameters.
- **Cursor pagination** for large or changing collections, with a link to the next page rather than page numbers that shift as rows are added.
- **Unambiguous values:** timestamps with an explicit time zone offset, ideally UTC; money as an amount plus a currency code; IDs as opaque strings that clients never parse.
- **Tolerant readers.** Say which enumerations may grow. Stripe's [versioning documentation](https://docs.stripe.com/api/versioning) tells integrators not to treat the documented values of an open enum as exhaustive; your consumers need the same warning, and your own clients should follow it.

## How to version an API and retire old versions

Most change should not need a new version. Adding an optional field, a new endpoint or a new optional parameter is backward-compatible if clients ignore what they do not know. Removing or renaming a field, changing a type, making an optional input required or changing what an error means is a breaking change, and an automated diff of the contract against the previous release flags these before a reviewer has to.

When a breaking change is unavoidable, teams usually pick one of three models:

| Model                 | How it works                                                         | In practice                                                                                                                                             |
| --------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Major version in path | `/v1/orders` and `/v2/orders` run side by side                       | Easy to route and to see in logs; each major version is another API to run until it is retired                                                          |
| Dated versions        | Each client is pinned to a dated version, or sends one in a header   | Stripe works this way: named major releases, backward-compatible monthly releases, a `Stripe-Version` header (`2026-08-26.dahlia` as of September 2026) |
| Continuous evolution  | No versions; fields are added, and old ones deprecated, then removed | GraphQL's [documented approach](https://graphql.org/learn/schema-design/); the spec's `@deprecated` directive marks what is leaving                     |

Whichever model you choose, retiring something takes a published policy and signals clients can read. Mark the operation `deprecated: true` in the OpenAPI contract, which tells consumers they should stop using it. Then say so in every response. The [Deprecation header](https://www.rfc-editor.org/rfc/rfc9745.html), a Standards Track RFC since March 2025, carries the deprecation date; a `Link` with `rel="deprecation"` points to the migration guide; and the [Sunset header](https://www.rfc-editor.org/rfc/rfc8594.html) (RFC 8594, May 2019) gives the date the resource is expected to stop responding, which must not be earlier than the deprecation date:

```http
HTTP/1.1 200 OK
Content-Type: application/json
Deprecation: @1790812799
Sunset: Thu, 30 Sep 2027 23:59:59 GMT
Link: <https://developer.example.com/orders-v2-migration>; rel="deprecation"; type="text/html"
```

The Deprecation value is a Unix timestamp (here, September 30, 2026 at 23:59:59 UTC). Deprecation does not change behaviour: the old version keeps working until the sunset date. Use that window to find who still calls it, from the gateway's logs per client, and contact them directly; headers are read by code, not by the people who have to schedule the migration.

> [!TIP]
> Publish the deprecation window before you need it. MCP's own specification, in its 2026-07-28 revision, adopted a feature lifecycle with a [minimum twelve-month deprecation window](https://modelcontextprotocol.io/specification/2026-07-28/changelog), which is the kind of promise partners can plan around.

## API gateways and API management

An API gateway is the single entry point for your APIs. [Microsoft's description of Azure API Management](https://learn.microsoft.com/en-us/azure/api-management/api-management-key-concepts) is typical of the category: the gateway accepts calls and routes them to backends, verifies API keys, JWTs and certificates, enforces quotas and rate limits, can transform requests and responses and cache results, and emits logs, metrics and traces. A management plane configures those policies, and a developer portal publishes documentation and onboards consumers. Azure also offers a self-hosted gateway, packaged as a Linux container, for APIs that run on premises or in other clouds. Kong, Apigee, Amazon API Gateway and Tyk are products in the same category.

Put in the gateway what is the same for every API: TLS, authentication, token and scope checks, rate limits and quotas, request size limits and logging. Keep in the service what depends on the data: whether this caller may see this record, business rules and validation of meaning. A gateway that tries to do both becomes a second application nobody tests.

When a client exceeds its limit, answer with 429 Too Many Requests, defined in [RFC 6585](https://www.rfc-editor.org/rfc/rfc6585.html), and a `Retry-After` header that says how long to wait. The IETF's [RateLimit header fields](https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/) (`RateLimit` and `RateLimit-Policy`) let a server announce the quota before it runs out; as of September 2026 they are still an Internet-Draft, so treat them as optional extras for well-behaved clients.

The gateway's catalogue also answers a question the OWASP list below asks: which APIs, hosts and versions are running right now. An API nobody remembers is an API nobody patches.

## API security: the OWASP API Security Top 10 and OAuth

The [OWASP Top 10 API Security Risks 2023](https://api-security.owasp.org/editions/2023/en/0x11-t10/) is still the current edition as of September 2026, and it reads as a checklist for API design reviews:

| Risk                                                 | What goes wrong                                                           | The control                                                   |
| ---------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------- |
| API1 Broken Object Level Authorization               | A caller reads or changes another user's object by changing its ID        | Ownership check in the service on every call that takes an ID |
| API2 Broken Authentication                           | Flawed sign-in lets attackers take over tokens or identities              | A standard identity provider, OAuth, short-lived tokens       |
| API3 Broken Object Property Level Authorization      | Responses expose, or requests can set, fields the caller should not touch | Explicit response schemas; allow-lists for writable fields    |
| API4 Unrestricted Resource Consumption               | Floods, huge queries or paid calls (SMS, email) run up cost               | Rate limits, quotas, page size and query cost limits          |
| API5 Broken Function Level Authorization             | A regular user reaches an admin function                                  | Deny by default; role checks per operation                    |
| API6 Unrestricted Access to Sensitive Business Flows | Automation abuses a flow such as buying or posting                        | Per-flow limits, bot defences, business monitoring            |
| API7 Server Side Request Forgery                     | The API fetches a URL the caller supplied                                 | Allow-list destinations; block internal addresses             |
| API8 Security Misconfiguration                       | Settings left at insecure defaults or missed in deployment                | Hardened defaults, checked in CI                              |
| API9 Improper Inventory Management                   | Forgotten versions and hosts stay online                                  | A catalogue of every API, version and host                    |
| API10 Unsafe Consumption of APIs                     | Data from a partner API is trusted more than user input                   | Validate third-party responses like any input                 |

[Broken object level authorization](https://api-security.owasp.org/editions/2023/en/0xa1-broken-object-level-authorization/) (BOLA) comes first because it is widespread and easy to exploit. The caller is authenticated and allowed to call the endpoint; the flaw is that the API trusts the object ID in the request. OWASP notes that comparing the user ID in the token with an ID parameter solves only a small subset of cases. The gateway cannot fix this: it knows the token is valid and carries the right scope, but not who owns the order in the request.

![A laptop's request passes a gateway with a key check and reaches a server. The server reaches for a record in another customer's cabinet and is stopped by an orange padlock at that record.](https://computese.com/images/blog/the-future-of-enterprise-api-development/bola.9bff2c3d86-1536.webp)

*The gateway accepted the token. Only the service knows whose record this is, so the check belongs there.*

The fix is an authorization check in every function that uses a client-supplied ID to reach a record, against your ownership and role rules, plus automated tests that try another tenant's IDs and fail the build when they succeed. Random, unguessable IDs make enumeration harder but do not replace the check. Our guide to [secure coding practices](https://computese.com/best-practices-for-secure-coding/) covers the same habits for the code behind the API.

For identity, the base standard is still OAuth 2.0 ([RFC 6749](https://www.rfc-editor.org/rfc/rfc6749.html), 2012), read together with the [OAuth 2.0 Security Best Current Practice](https://www.rfc-editor.org/rfc/rfc9700.html) (RFC 9700, January 2025). The BCP asks for access tokens restricted to the minimum privileges a client needs and audience-restricted to the resource server that will receive them, which that server must verify on every request. [OAuth 2.1](https://datatracker.ietf.org/doc/draft-ietf-oauth-v2-1/) folds those lessons into one document: PKCE is required for the authorization code flow, the implicit and resource owner password grants are gone, redirect URIs must match exactly, and bearer tokens may not travel in query strings. As of September 2026 it is still a working group draft (revision 16, dated September 3, 2026), with submission to the IESG planned for December 2026, but nothing in it stops you from following it today.

In practice: users sign in through the authorization code flow with PKCE, services call each other with client credentials, each client gets only the scopes it needs, and API keys identify applications rather than people and are stored and rotated like any other secret.

## API governance: style guides and linting

Governance is what makes APIs built by different teams look like one company's work. It has two parts: a written style guide, and automation that enforces the parts a machine can check.

A style guide records decisions once: resource naming, pagination, error format, versioning, date and money formats, which OAuth scopes exist. Google publishes its own as [API Improvement Proposals](https://google.aip.dev/1), the source of truth for API guidance at Google and the basis for reviewers' comments, and it is a useful model even if you adopt none of its rules.

The machine-checkable part runs in CI on every pull request that touches a contract. [Spectral](https://github.com/stoplightio/spectral) is an open-source JSON and YAML linter with built-in rulesets for OpenAPI (including 3.2), AsyncAPI and Arazzo, and custom rules for your own guide:

```yaml
extends: ["spectral:oas"]
rules:
  operation-operationId: error
  oas3-operation-security-defined: error
  paths-kebab-case:
    description: Path segments use lower-case kebab-case.
    severity: warn
    given: "$.paths[*]~"
    then:
      function: pattern
      functionOptions:
        match: "^(/|[a-z0-9-.]+|{[a-zA-Z0-9_]+})+$"
```

```bash
npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml
```

Add a breaking-change diff against the last released contract, and keep human review for what linters cannot judge: whether the resources model the business correctly, and whether a new API should exist at all.

## Observability: trace every call, including an agent's

When an integration fails in the middle of the night, the first question is always the same: which call, from which client, failed where. Three habits answer it.

1. **Propagate trace context.** The [W3C Trace Context](https://www.w3.org/TR/trace-context/) Recommendation defines the `traceparent` and `tracestate` headers that carry one trace ID across the gateway, your services and your queues. Have the gateway start a trace when a request arrives without one.
2. **Name spans and metrics by route, not by URL.** OpenTelemetry's [HTTP semantic conventions](https://opentelemetry.io/docs/specs/semconv/http/http-spans/) name server spans by method and the matched route template (`http.route`), which must be low-cardinality: `GET /orders/{orderId}`, not one series per order.
3. **Measure per consumer.** Record the client ID with every request, so request rate, error rate and latency can be read per partner, per application and per agent, and alerts reach the team that owns the flow.

Log enough to replay a problem and nothing that becomes a liability: never full tokens or passwords, and personal data only where you have a reason to keep it. AI agents are joining the same traces: MCP's 2026-07-28 specification documents how `traceparent`, `tracestate` and `baggage` travel in its messages, so a tool call can be followed into your API.

## AI agents as API consumers: the Model Context Protocol

AI agents reach tools and data through a shared protocol: the Model Context Protocol. Anthropic [open-sourced MCP on November 25, 2024](https://www.anthropic.com/news/model-context-protocol) as an open standard for connecting AI assistants to the systems where data lives. In the [specification's terms](https://modelcontextprotocol.io/specification/2026-07-28), hosts (AI applications) use MCP clients to connect to MCP servers, which offer tools the model can call, resources it can read and prompts users can pick. Messages are JSON-RPC 2.0, over a local stdio connection or over Streamable HTTP, and each tool declares its inputs as JSON Schema, which defaults to the same 2020-12 dialect that OpenAPI 3.2 uses. That is why an OpenAPI operation can map onto an MCP tool with little translation.

MCP is no longer one vendor's protocol. On December 9, 2025 the Linux Foundation [formed the Agentic AI Foundation](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation) with MCP as a founding project, alongside Block's goose and OpenAI's AGENTS.md; the announcement counted more than 10,000 published MCP servers. The project is [now established](https://modelcontextprotocol.io/community/governance) as a Series of LF Projects, LLC, with specification contributions under the Apache License 2.0, a hierarchy of maintainers, core maintainers and lead maintainers, and working groups that produce Specification Enhancement Proposals (SEPs). Our [AI frameworks comparison](https://computese.com/latest-ai-tools-and-frameworks-a-comparative-analysis/) covers the agent frameworks and SDKs that use it.

Versions are dates, the last day of a backward-incompatible change, and [the current protocol version](https://modelcontextprotocol.io/specification/versioning) is 2026-07-28. That revision made the protocol stateless: the initialization handshake and protocol-level sessions are gone, and every request carries its protocol version and client capabilities. It also deprecated the Roots, Sampling and Logging features, which is a reminder to pin the version you build against.

For HTTP transports, [MCP authorization](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization) is built on OAuth. Authorization is optional, but a protected MCP server acts as an OAuth 2.1 resource server: it must publish OAuth 2.0 Protected Resource Metadata (RFC 9728) so clients can find its authorization server, clients must name the server they want a token for using Resource Indicators (RFC 8707), and the server must accept only tokens issued for it and must not pass them through to other services. Local stdio servers take their credentials from the environment instead.

Gateways are adding MCP as another front door. [Azure API Management](https://learn.microsoft.com/en-us/azure/api-management/export-rest-mcp-server), for example, can expose operations of a REST API it already manages as tools on a remote MCP server, with the gateway's policies applied to every tool; as of September 2026 it exposes tools this way, but not MCP resources or prompts. Whether you use a gateway feature or write the server yourself, the pattern is the same: the MCP server is another client of your API, not a shortcut around it.

## What changes when the caller is an AI agent

A person using your app is limited by the screens you built. An agent is limited only by the tools and permissions you give it, and it acts at machine speed on instructions that might be wrong or planted. OWASP's [LLM06:2025 Excessive Agency](https://genai.owasp.org/llmrisk/llm062025-excessive-agency/) traces the damage to three root causes: excessive functionality, excessive permissions and excessive autonomy. Each maps to something the API owner controls.

| Concern        | A person using an app                  | An AI agent calling your API                 | What to change                                                                              |
| -------------- | -------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------- |
| Permissions    | The interface limits what can be tried | Any tool it is given, in any order           | Separate read and write tools; narrow scopes; act as the user, never a shared admin account |
| Volume         | Bounded by how fast people click       | Loops and retries at machine speed           | Per-agent and per-user rate limits and quotas                                               |
| Mistakes       | A person notices a wrong screen        | Can act on a misread or injected instruction | Confirmation for destructive actions; authorization enforced in the API                     |
| Accountability | Session logs name the user             | Several agents may act for one user          | Log user, agent client, tool, arguments and outcome                                         |
| Errors         | A person reads the message             | The model reads it and tries again           | Problem details that say what to fix                                                        |

**Scopes.** Give each agent its own OAuth client, then apply what RFC 9700 already recommends for every client: the minimum privileges, and tokens restricted to your API as their audience. The MCP authorization specification adds scope guidance of its own: a server returns the scopes an operation needs in its `WWW-Authenticate` challenge, clients start from a minimal set and step up when an operation requires more. Run the agent in the user's context, so it can never see more than the user could.

**Rate limits.** The [MCP tools specification](https://modelcontextprotocol.io/specification/2026-07-28/server/tools) requires servers to validate tool inputs, implement access controls and rate limit tool invocations. Apply limits at the API as well, per agent client and per user, so one runaway loop cannot starve your human users or run up a bill.

**Audit and confirmation.** The same specification says clients should log tool usage for audit, prompt the user before sensitive operations, and keep a human able to deny any tool call. Do not rely on the client: record in your own logs which user, which agent client and which tool made each call, with the trace ID, and require an explicit confirmation step in the API for irreversible actions such as payments or deletions.

![An agent box with a chip symbol calls tools on an MCP server through a gate holding an orange scoped key, with a rate meter beside the gate and every call copied onto a log sheet.](https://computese.com/images/blog/the-future-of-enterprise-api-development/agent.3abd3612c7-1536.webp)

*An agent should reach your systems through a narrow key, a meter and a log, never around them.*

Two more differences are easy to miss. Tool names and descriptions become part of the model's input, so write them as carefully as documentation. On the consuming side, the tools specification tells clients to treat tool annotations as untrusted unless the server is trusted, and third-party MCP servers deserve the same review as any dependency; our look at [how attackers target AI tools](https://computese.com/the-dual-role-of-ai/) covers that supply chain. And make authorization decisions in the API, which OWASP calls complete mediation, never by asking the model whether an action is allowed.

## An enterprise API checklist for 2026

An API strategy is these decisions written down and applied to every API, not only the next one. In order:

1. Keep a catalogue of every API, version, host and owner, and retire what nobody claims.
2. Write the contract first: OpenAPI 3.2 for HTTP, AsyncAPI 3.1 for events, stored in git beside the code.
3. Lint every contract change in CI against your style guide, with a breaking-change diff.
4. Generate mocks, SDKs, documentation and contract tests from the contract.
5. Choose the style per flow: REST for partners, GraphQL for data-hungry front ends, gRPC inside, webhooks and events for change notifications.
6. Standardize errors on RFC 9457 and require idempotency keys on retried POSTs.
7. Put authentication, scopes, rate limits and logging in the gateway, and object-level authorization in the service.
8. Follow RFC 9700 now and track OAuth 2.1; sign and verify every webhook.
9. Propagate W3C trace context and measure per consumer.
10. Publish a deprecation policy and send Deprecation and Sunset headers.
11. For AI agents, expose tools through MCP on top of your API, with separate clients, narrow scopes, rate limits, confirmation for destructive actions and an audit log.

If you want help with this, our [integrations service](https://computese.com/services/integrations/) builds well-designed APIs for your own systems, with REST and GraphQL, OpenAPI contracts and versioning, scoped OAuth 2.0 and API keys, rate limits, and webhooks with signature verification. When the API sits behind a customer portal or dashboard, our [web design and development team](https://computese.com/services/web-design-development/) builds web applications with the identity, roles and APIs behind them. More on connecting systems is under [integrations](https://computese.com/category/integrations/).

## Key terms
- **API-first design**: Designing and agreeing an API's contract before writing the code that implements it, so the contract, not the implementation, is the source of truth.
- **OpenAPI Specification (OAS)**: The standard, language-neutral format for describing HTTP APIs: paths, operations, parameters, schemas, security and errors. Version 3.2.1 is current as of September 2026.
- **AsyncAPI**: The equivalent contract format for message-driven APIs, such as topics on Kafka, AMQP queues, MQTT or WebSockets. Version 3.1.0 is current.
- **API gateway**: The entry point that receives every API call, checks credentials, applies rate limits and quotas, routes the call to a backend and records logs, metrics and traces.
- **Broken object level authorization (BOLA)**: A flaw where an API returns or changes an object because the caller supplied its ID, without checking that the caller may access that object. API1 in the OWASP API Security Top 10 2023.
- **OAuth 2.1**: An IETF draft that consolidates OAuth 2.0 and its security fixes: PKCE for the authorization code flow, no implicit or password grants, exact redirect matching. Still a draft in September 2026.
- **Deprecation and Sunset headers**: HTTP response headers that tell clients a resource is deprecated (RFC 9745) and when it is expected to stop responding (RFC 8594).
- **Idempotency key**: A unique value a client sends with a request that is not naturally idempotent, such as POST, so the server can recognize a retry and return the first result instead of acting twice.
- **Model Context Protocol (MCP)**: An open protocol, introduced by Anthropic in November 2024, that lets AI applications discover and call tools, read resources and use prompts exposed by MCP servers, over JSON-RPC 2.0.

## Common questions

### What is enterprise API development?

It is the design, build and operation of APIs that many systems and teams depend on: partner and public APIs, internal platforms and the integrations between business systems. Compared with a single app's private API, it adds contracts, versioning policies, a gateway, security review, governance and monitoring per consumer.

### What does API-first mean?

API-first means the API contract is designed and agreed before the implementation. For HTTP APIs the contract is an OpenAPI description, currently version 3.2.1; for event-driven APIs it is AsyncAPI. Mocks, SDKs, documentation and contract tests are then generated from it, so teams can work in parallel.

### Should we use REST, GraphQL or gRPC?

Use REST over HTTP for most partner and public APIs, because every client, proxy and gateway understands it. Use GraphQL where front ends assemble many related objects per screen, and gRPC for internal service-to-service calls that need low latency and streaming. Many enterprises run all three, chosen per flow.

### How should we version an API?

Make additive, backward-compatible changes without a new version, and reserve a new major version for breaking ones. Whether the version sits in the URL or a header matters less than having a written policy: mark retired operations deprecated in the contract, send Deprecation and Sunset headers, and give consumers a migration window.

### What is the most common API security risk?

Broken object level authorization, API1 in the OWASP API Security Top 10 2023: the API trusts an object ID from the request without checking that the caller may access that object. The fix is an authorization check in every function that uses a client-supplied ID, plus tests that try another user's IDs.

### Do our APIs need an MCP server for AI agents?

Only if you want AI agents, your staff's or your customers', to use your systems as tools. When you do, build the MCP server on top of your existing API with its own client identity, narrow OAuth scopes, rate limits and audit logging, rather than giving it direct database access.

## Sources
1. [OpenAPI Specification v3.2.1](https://spec.openapis.org/oas/v3.2.1.html), OpenAPI Initiative
2. [RFC 10008: The HTTP QUERY Method](https://www.rfc-editor.org/rfc/rfc10008.html), IETF
3. [AsyncAPI Specification 3.1.0](https://www.asyncapi.com/docs/reference/specification/v3.1.0), AsyncAPI Initiative
4. [AsyncAPI 3.0.0 Release Notes](https://www.asyncapi.com/blog/release-notes-3.0.0), AsyncAPI Initiative
5. [The Arazzo Specification v1.1.0](https://spec.openapis.org/arazzo/latest.html), OpenAPI Initiative
6. [RFC 9110: HTTP Semantics](https://www.rfc-editor.org/rfc/rfc9110.html), IETF
7. [Serving over HTTP](https://graphql.org/learn/serving-over-http/), GraphQL Foundation
8. [GraphQL Specification, September 2025 Edition](https://spec.graphql.org/September2025/), GraphQL Foundation
9. [Introduction to gRPC](https://grpc.io/docs/what-is-grpc/introduction/), gRPC Authors
10. [gRPC FAQ](https://grpc.io/docs/what-is-grpc/faq/), gRPC Authors
11. [Validating webhook deliveries](https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries), GitHub Docs
12. [RFC 9457: Problem Details for HTTP APIs](https://www.rfc-editor.org/rfc/rfc9457.html), IETF
13. [Idempotent requests](https://docs.stripe.com/api/idempotent_requests), Stripe
14. [Versioning](https://docs.stripe.com/api/versioning), Stripe
15. [Schema Design: versioning](https://graphql.org/learn/schema-design/), GraphQL Foundation
16. [RFC 9745: The Deprecation HTTP Response Header Field](https://www.rfc-editor.org/rfc/rfc9745.html), IETF
17. [RFC 8594: The Sunset HTTP Header Field](https://www.rfc-editor.org/rfc/rfc8594.html), IETF
18. [Key Changes (specification 2026-07-28)](https://modelcontextprotocol.io/specification/2026-07-28/changelog), Model Context Protocol
19. [Azure API Management key concepts](https://learn.microsoft.com/en-us/azure/api-management/api-management-key-concepts), Microsoft Learn
20. [RFC 6585: Additional HTTP Status Codes](https://www.rfc-editor.org/rfc/rfc6585.html), IETF
21. [RateLimit header fields for HTTP (draft-ietf-httpapi-ratelimit-headers)](https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/), IETF
22. [OWASP Top 10 API Security Risks, 2023](https://api-security.owasp.org/editions/2023/en/0x11-t10/), OWASP API Security Project
23. [API1:2023 Broken Object Level Authorization](https://api-security.owasp.org/editions/2023/en/0xa1-broken-object-level-authorization/), OWASP API Security Project
24. [RFC 6749: The OAuth 2.0 Authorization Framework](https://www.rfc-editor.org/rfc/rfc6749.html), IETF
25. [RFC 9700: Best Current Practice for OAuth 2.0 Security](https://www.rfc-editor.org/rfc/rfc9700.html), IETF
26. [The OAuth 2.1 Authorization Framework (draft-ietf-oauth-v2-1)](https://datatracker.ietf.org/doc/draft-ietf-oauth-v2-1/), IETF
27. [AIP-1: AIP Purpose and Guidelines](https://google.aip.dev/1), Google
28. [Spectral](https://github.com/stoplightio/spectral), Stoplight
29. [Trace Context](https://www.w3.org/TR/trace-context/), W3C
30. [Semantic conventions for HTTP spans](https://opentelemetry.io/docs/specs/semconv/http/http-spans/), OpenTelemetry
31. [Introducing the Model Context Protocol](https://www.anthropic.com/news/model-context-protocol), Anthropic
32. [Specification, version 2026-07-28](https://modelcontextprotocol.io/specification/2026-07-28), Model Context Protocol
33. [Linux Foundation Announces the Formation of the Agentic AI Foundation (AAIF)](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation), Linux Foundation
34. [Governance and Stewardship](https://modelcontextprotocol.io/community/governance), Model Context Protocol
35. [Versioning](https://modelcontextprotocol.io/specification/versioning), Model Context Protocol
36. [Authorization (specification 2026-07-28)](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization), Model Context Protocol
37. [Expose REST API in API Management as an MCP server](https://learn.microsoft.com/en-us/azure/api-management/export-rest-mcp-server), Microsoft Learn
38. [LLM06:2025 Excessive Agency](https://genai.owasp.org/llmrisk/llm062025-excessive-agency/), OWASP Gen AI Security Project
39. [Tools (specification 2026-07-28)](https://modelcontextprotocol.io/specification/2026-07-28/server/tools), Model Context Protocol