OpenAI’s DevDay last week was mostly pitched as an agents event. Persistent agents, cloud Codex, a cheaper model. Fine. But if you’re learning to build and design APIs, two of the smaller releases are worth more of your attention than the headline model, because they say a lot about where API contracts are going.

Here’s what shipped, then what to take from it.

What OpenAI released

The Agents API is now in public beta. It runs agents on OpenAI’s own infrastructure, with memory, tool calling, tool search, context compaction and multi-agent support carried over from Codex. The new piece is computer use: an agent can now drive software through its graphical interface, clicking and typing the way a person would.

Every few weeks someone asks whether MCP replaces REST. It does not. The question is still worth answering carefully, because the line between the two moved in July, and most of the explanations written before then are now describing a protocol that no longer exists.

An HTTP API is a contract between two pieces of software written by people who read documentation. A developer opens the reference, learns that POST /v1/invoices wants a customer ID and an array of line items, writes the call, and ships it. The knowledge lived in a human head at build time and then got frozen into source code. When the endpoint changes, something breaks in production and a person goes and fixes it.

Sixty-six sites, 18,880 visits and 19,950 page views for the week of August 30 to September 5. Visits rose 14.91% and page views 17.01%, which is a good week by any reading of the top line. The median page load time across the network went the other way, climbing 28.64% to 3,579ms, and that single figure complicates the rest of the report.

technologies.org led again with 2.44k visits and 2.52k page views, up 74.29% and 76.22% respectively, on a load time of 2,561ms (up 8.8%). Chrome accounted for 1.32k of those sessions against 1.05k logged as Unknown, with a further 30 from ChromeMobileWebview. Its LCP at the 75th percentile improved by a third to 2,704ms even as the raw load time crept up, so the main content is painting faster while the tail of the load stretches out. CLS came in at 1, up 262.32%, and INP at 40ms. In second place, marketresearchmedia.com posted 1.17k visits and 1.17k page views, both up 265.62%, making it the largest mover in the report and also its worst performer on speed: load time nearly tripled to 7,454ms and the 75th percentile LCP went up almost fivefold to 4,988ms. Chrome carried 1.02k of those sessions, Unknown 110, ChromeMobile 10. Visits and page views are identical, so every session ended on the page it began on. Third, analysis.org held steady at 1.1k visits (up 8.91%) and 1.12k page views (up 9.8%), and delivered the clearest genuine improvement in the report with a load time down 21.99% to 3,579ms after weeks in five figures. Its LCP eased 10.42% to 3,680ms, CLS sat flat at 1, INP at 40ms. Unusually for the top three, Unknown outnumbered Chrome here, 660 to 390, with 20 on ChromeMobile.

Istio 1.31 is out, and one line in the release notes says a lot about where API infrastructure is heading. You can now run agentgateway, a proxy built for AI agent and MCP traffic, as a waypoint inside the mesh.

If “waypoint” means nothing to you yet, that’s fine. Here’s the short version, then why it matters if you build APIs.

What changed in 1.31

Istio’s ambient mode splits the mesh in two. A small per-node component handles encryption and basic connectivity. Anything that needs to understand HTTP, like routing, auth policy or rate limits, goes through a separate proxy called a waypoint. You opt services into a waypoint with a label.

An API gateway is a server that sits between clients and backend services, acting as the single entry point through which all API traffic passes. Every request goes through the gateway, which can inspect, modify, authenticate, route, transform, and rate-limit that traffic before it reaches any backend service. For teams running multiple services, an API gateway centralizes concerns that would otherwise be duplicated across every service independently.

Understanding what a gateway provides — and what it does not — is the prerequisite to deciding whether one belongs in your architecture.

APIs that external developers pay to use require more than good technical design. They require a pricing model that aligns cost with value, metering infrastructure that accurately tracks usage, and billing systems that translate usage into charges reliably. These are product and engineering concerns that compound — a poorly designed pricing model produces integrators who spend more time managing API costs than building their product, and metering infrastructure that loses events produces disputes and lost revenue.

Cloudflare just published the results of an experiment that every API developer should read, even if you’ll never run a firewall. The company put frontier AI models inside a test harness and told them to get past its own Web Application Firewall.

They found gaps. Not many, but the pattern of what got through is the real lesson.

What Cloudflare did

The test started with attack payloads the WAF already blocked. Instead of replaying a fixed list, the models looked at how each attempt was handled and proposed a tweak for the next one: different encoding, different placement in the request, different delivery. They had no access to the WAF rules or source code. Pure black box.

Authentication is where most API integrations go wrong the first time. Not because the concepts are complicated, but because there are several distinct mechanisms in common use, they solve different problems, and developers often reach for the one they recognize rather than the one that fits. Understanding what each mechanism actually does — and what it does not do — is the difference between an integration that works and one that works until it doesn’t.

API security failures are not exotic. They rarely involve sophisticated attacks on cryptographic primitives or novel zero-day exploits. The most consequential breaches — the ones that expose millions of records, compromise user accounts, or shut down services — happen because an API allowed something it should not have, at a scale its designers did not anticipate. Understanding the fundamental attack surface of an API and designing against it deliberately is the entire discipline. It is not advanced knowledge. It is the baseline.

CORS is the source of more developer frustration than almost any other browser security mechanism — not because it is poorly designed, but because its error messages are opaque, its rules are non-obvious, and it only manifests in a specific context that server-side developers often do not encounter during development. Understanding what CORS actually is and why it exists transforms it from an arbitrary obstacle into a predictable system with clear rules.

Most SaaS APIs are multi-tenant: the same infrastructure serves many customers, each operating in isolation from the others. A user of Tenant A should never see, modify, or even know about the data of Tenant B. This isolation is the foundational guarantee of a multi-tenant system, and it must hold at every layer of the stack — not just at the query level, but at the API design level, the authentication level, and the operational level.

Every API integration has a bootstrap problem. To build against an API, you need to call it. To call it safely during development, you need an environment that will not charge your card, send real emails, or bill real users. To build that environment, you need to understand how the API works — which requires calling it. This circularity is why sandboxes and mocks exist, and why both are worth understanding deeply.

Testing an API is not the same as testing a library or a UI. An API is a contract — a public interface that other systems depend on — and the testing strategy must reflect that. Unit tests tell you whether individual functions work. Integration tests tell you whether the system behaves correctly end to end. Contract tests tell you whether the API still honors its published interface. Load tests tell you when it breaks. All four serve distinct purposes and none is a substitute for the others.

Istio 1.31 is out, and one line in the release notes says a lot about where API infrastructure is heading. You can now run agentgateway, a proxy built for AI agent and MCP traffic, as a waypoint inside the mesh.

If “waypoint” means nothing to you yet, that’s fine. Here’s the short version, then why it matters if you build APIs.

What changed in 1.31

Istio’s ambient mode splits the mesh in two. A small per-node component handles encryption and basic connectivity. Anything that needs to understand HTTP, like routing, auth policy or rate limits, goes through a separate proxy called a waypoint. You opt services into a waypoint with a label.

An API gateway is a server that sits between clients and backend services, acting as the single entry point through which all API traffic passes. Every request goes through the gateway, which can inspect, modify, authenticate, route, transform, and rate-limit that traffic before it reaches any backend service. For teams running multiple services, an API gateway centralizes concerns that would otherwise be duplicated across every service independently.

Understanding what a gateway provides — and what it does not — is the prerequisite to deciding whether one belongs in your architecture.

Most SaaS APIs are multi-tenant: the same infrastructure serves many customers, each operating in isolation from the others. A user of Tenant A should never see, modify, or even know about the data of Tenant B. This isolation is the foundational guarantee of a multi-tenant system, and it must hold at every layer of the stack — not just at the query level, but at the API design level, the authentication level, and the operational level.

Every API starts with a choice that will shape every decision that follows: what protocol are you building on? REST, GraphQL, and gRPC are the three dominant options in modern API development, and none of them is universally correct. Each reflects a different set of assumptions about who is calling the API, how often, and what they need back.

Understanding the tradeoffs is not optional knowledge for serious API developers. It is the foundation.

HTTP is a synchronous protocol. A client sends a request and waits for a response. This works well for operations that complete in milliseconds — a database read, a record update, a validation check. It breaks down for operations that take seconds, minutes, or longer: video transcoding, report generation, bulk data exports, machine learning inference on large inputs, email campaigns to millions of recipients.

Holding an HTTP connection open for a minute or more is technically possible and practically wrong. Clients time out. Load balancers have maximum request durations. Users cannot tell the difference between a server still working and a server that silently failed. Long synchronous operations produce brittle integrations and poor user experiences.

Authentication is where most API integrations go wrong the first time. Not because the concepts are complicated, but because there are several distinct mechanisms in common use, they solve different problems, and developers often reach for the one they recognize rather than the one that fits. Understanding what each mechanism actually does — and what it does not do — is the difference between an integration that works and one that works until it doesn’t.

API security failures are not exotic. They rarely involve sophisticated attacks on cryptographic primitives or novel zero-day exploits. The most consequential breaches — the ones that expose millions of records, compromise user accounts, or shut down services — happen because an API allowed something it should not have, at a scale its designers did not anticipate. Understanding the fundamental attack surface of an API and designing against it deliberately is the entire discipline. It is not advanced knowledge. It is the baseline.

HTTP was designed from the beginning to support multiple representations of the same resource. A user profile can be represented as JSON for a machine consumer or as HTML for a browser. A dataset can be returned as JSON or as CSV depending on what the client intends to do with it. An image can be served as JPEG or WebP based on what the browser supports. Content negotiation is the mechanism through which clients and servers agree on which representation to use — and understanding it is essential for building APIs that serve diverse consumers cleanly.

Caching is one of the highest-leverage performance improvements available to an API, and one of the least consistently implemented. A response that is cached at the right layer — in a CDN, a reverse proxy, or the client itself — eliminates a server round trip entirely. At scale, that elimination compounds: fewer database queries, lower infrastructure cost, faster responses for every consumer. The HTTP specification provides a complete, standardized caching system. Most APIs use it only partially, leaving significant headroom unrealized.

Cloudflare just published the results of an experiment that every API developer should read, even if you’ll never run a firewall. The company put frontier AI models inside a test harness and told them to get past its own Web Application Firewall.

They found gaps. Not many, but the pattern of what got through is the real lesson.

What Cloudflare did

The test started with attack payloads the WAF already blocked. Instead of replaying a fixed list, the models looked at how each attempt was handled and proposed a tweak for the next one: different encoding, different placement in the request, different delivery. They had no access to the WAF rules or source code. Pure black box.

Sixty-six sites, 18,880 visits and 19,950 page views for the week of August 30 to September 5. Visits rose 14.91% and page views 17.01%, which is a good week by any reading of the top line. The median page load time across the network went the other way, climbing 28.64% to 3,579ms, and that single figure complicates the rest of the report.

technologies.org led again with 2.44k visits and 2.52k page views, up 74.29% and 76.22% respectively, on a load time of 2,561ms (up 8.8%). Chrome accounted for 1.32k of those sessions against 1.05k logged as Unknown, with a further 30 from ChromeMobileWebview. Its LCP at the 75th percentile improved by a third to 2,704ms even as the raw load time crept up, so the main content is painting faster while the tail of the load stretches out. CLS came in at 1, up 262.32%, and INP at 40ms. In second place, marketresearchmedia.com posted 1.17k visits and 1.17k page views, both up 265.62%, making it the largest mover in the report and also its worst performer on speed: load time nearly tripled to 7,454ms and the 75th percentile LCP went up almost fivefold to 4,988ms. Chrome carried 1.02k of those sessions, Unknown 110, ChromeMobile 10. Visits and page views are identical, so every session ended on the page it began on. Third, analysis.org held steady at 1.1k visits (up 8.91%) and 1.12k page views (up 9.8%), and delivered the clearest genuine improvement in the report with a load time down 21.99% to 3,579ms after weeks in five figures. Its LCP eased 10.42% to 3,680ms, CLS sat flat at 1, INP at 40ms. Unusually for the top three, Unknown outnumbered Chrome here, 660 to 390, with 20 on ChromeMobile.

CORS is the source of more developer frustration than almost any other browser security mechanism — not because it is poorly designed, but because its error messages are opaque, its rules are non-obvious, and it only manifests in a specific context that server-side developers often do not encounter during development. Understanding what CORS actually is and why it exists transforms it from an arbitrary obstacle into a predictable system with clear rules.

A browser can open an API URL, but curl lets you see the request and response more closely. In this lesson you will start a small local server, fetch a JSON response, inspect its headers and send a JSON body. You need Python 3 and curl installed. The server is deliberately small and runs only on your own computer.

Create a file called server.py with the following code:

from http.server import BaseHTTPRequestHandler, HTTPServer
import json

class Handler(BaseHTTPRequestHandler):
    def do_GET(self):
        body = json.dumps({"name": "tea", "id": 1}).encode()
        self.send_response(200)
        self.send_header("Content-Type", "application/json")
        self.end_headers()
        self.wfile.write(body)

    def do_POST(self):
        body = self.rfile.read(int(self.headers.get("Content-Length", 0)))
        try:
            data = json.loads(body)
        except ValueError:
            self.send_error(400)
            return
        result = json.dumps({"received": data}).encode()
        self.send_response(201)
        self.send_header("Content-Type", "application/json")
        self.end_headers()
        self.wfile.write(result)

HTTPServer(("127.0.0.1", 18766), Handler).serve_forever()

Run python3 server.py in a terminal and leave it running. Open another terminal for the curl commands below. The address 127.0.0.1 points to your own machine. This toy service returns the same item for any GET path and echoes JSON sent to any POST path; it does not save anything.

Every API feature eventually reaches the end of its useful life. The endpoint was designed before the domain was understood. The schema made assumptions that no longer hold. A better approach exists. The old version must go. How you handle that retirement determines whether your API’s integrators trust you or resent you.

Deprecation done well is a communication and scheduling problem. Deprecation done poorly is a breaking change that happens without warning.

Every API integration has a bootstrap problem. To build against an API, you need to call it. To call it safely during development, you need an environment that will not charge your card, send real emails, or bill real users. To build that environment, you need to understand how the API works — which requires calling it. This circularity is why sandboxes and mocks exist, and why both are worth understanding deeply.

Developer experience is not a soft concern. It determines how quickly developers integrate your API, how many support tickets they file, how many abandon the integration and use a competitor, and how they describe your product to other developers. An API with good developer experience turns integrators into advocates. An API with poor developer experience turns them into complaints.

Good DX is not a single feature or a checklist item added at the end of the design process. It emerges from a series of small decisions made throughout design and implementation. Every naming convention, every error message, every documentation page, and every SDK is a DX decision.

Documentation is the first thing a developer encounters and the last thing most teams prioritize. The result is a familiar pattern: the API is built, the launch deadline approaches, documentation gets written in a hurry by someone who did not build the API and does not fully understand it, and integrators spend the next six months filing support tickets that could have been answered by better documentation. OpenAPI exists to break that cycle by making documentation a first-class artifact of the API itself.

REST APIs organize their surface around resources — the nouns of your domain. How you identify, name, and structure those resources determines whether your API feels intuitive or requires constant documentation reference. Good URL design is not aesthetic preference. It is communication: URLs tell developers what the API contains, how it is organized, and how to navigate it. Done well, a developer can infer what endpoints exist from the ones they already know.

Developer experience is not a soft concern. It determines how quickly developers integrate your API, how many support tickets they file, how many abandon the integration and use a competitor, and how they describe your product to other developers. An API with good developer experience turns integrators into advocates. An API with poor developer experience turns them into complaints.

Good DX is not a single feature or a checklist item added at the end of the design process. It emerges from a series of small decisions made throughout design and implementation. Every naming convention, every error message, every documentation page, and every SDK is a DX decision.

Documentation is the first thing a developer encounters and the last thing most teams prioritize. The result is a familiar pattern: the API is built, the launch deadline approaches, documentation gets written in a hurry by someone who did not build the API and does not fully understand it, and integrators spend the next six months filing support tickets that could have been answered by better documentation. OpenAPI exists to break that cycle by making documentation a first-class artifact of the API itself.

The curl lesson showed what an API exchange looks like by hand. This one moves the same work into Python with the requests library. By the end you’ll have a small client function that sets a timeout on every call, reuses one connection, and turns every way a call can fail into one clear error your code can act on.

You need Python 3.10 or newer, which is the minimum for the current requests release (2.34.2). Everything runs against a test server on your own machine, so no account or API key is involved.

Errors are not edge cases in API development. They are a primary output. Every API call that can fail will fail — due to invalid input, authentication problems, resource conflicts, rate limits, or infrastructure issues — and how an API communicates those failures determines whether integrators can handle them gracefully or are left guessing. An API that returns clear, consistent, actionable errors is a well-designed API. Everything else is guesswork at scale.

An API that works in development and fails in production in ways you cannot diagnose is worse than an API that fails loudly. Production is where assumptions meet reality, and the gap between them only becomes visible if you can see what is happening inside the system. Observability is the discipline of making distributed systems understandable — building in enough visibility that when something goes wrong, you can find out what, where, and why without guessing.

The standard REST pattern is one resource per request. Create one user, update one order, fetch one product. This works until an integrator needs to create ten thousand users, update five hundred orders, or sync an entire product catalog. Making ten thousand individual API calls is slow, expensive in terms of rate limit quota, and brittle — a network failure on request 7,432 leaves the integrator with a partially completed operation and no clean recovery path.

Developer experience is not a soft concern. It determines how quickly developers integrate your API, how many support tickets they file, how many abandon the integration and use a competitor, and how they describe your product to other developers. An API with good developer experience turns integrators into advocates. An API with poor developer experience turns them into complaints.

Good DX is not a single feature or a checklist item added at the end of the design process. It emerges from a series of small decisions made throughout design and implementation. Every naming convention, every error message, every documentation page, and every SDK is a DX decision.

File handling is where many otherwise well-designed APIs cut corners. The result is integrations that work fine for small files and break under production conditions: uploads timing out on slow connections, downloads failing midway through large transfers, clients with no way to resume an interrupted operation. File upload and download have well-established patterns that handle these conditions correctly. Most of them require explicit design choices rather than the defaults.

Simple Upload: When It Is Sufficient

For files under a few megabytes that users upload infrequently, a direct multipart form upload to your API is the simplest approach. The client sends a multipart/form-data POST request with the file as one part and any metadata as additional parts or as a separate JSON field:

GraphQL shifts the design work from endpoint definition to schema design. The schema is the API — every type, field, query, and mutation is declared in the schema, and the schema governs everything the API can do. Designing a GraphQL schema well requires understanding how types compose, how to express mutations that reflect real domain operations, and where GraphQL’s conventions differ meaningfully from REST patterns that GraphQL developers often import by habit.

Every API starts with a choice that will shape every decision that follows: what protocol are you building on? REST, GraphQL, and gRPC are the three dominant options in modern API development, and none of them is universally correct. Each reflects a different set of assumptions about who is calling the API, how often, and what they need back.

Understanding the tradeoffs is not optional knowledge for serious API developers. It is the foundation.

Every API starts with a choice that will shape every decision that follows: what protocol are you building on? REST, GraphQL, and gRPC are the three dominant options in modern API development, and none of them is universally correct. Each reflects a different set of assumptions about who is calling the API, how often, and what they need back.

Understanding the tradeoffs is not optional knowledge for serious API developers. It is the foundation.

The curl lesson showed what an API exchange looks like by hand. This one moves the same work into Python with the requests library. By the end you’ll have a small client function that sets a timeout on every call, reuses one connection, and turns every way a call can fail into one clear error your code can act on.

You need Python 3.10 or newer, which is the minimum for the current requests release (2.34.2). Everything runs against a test server on your own machine, so no account or API key is involved.

A browser can open an API URL, but curl lets you see the request and response more closely. In this lesson you will start a small local server, fetch a JSON response, inspect its headers and send a JSON body. You need Python 3 and curl installed. The server is deliberately small and runs only on your own computer.

Create a file called server.py with the following code:

from http.server import BaseHTTPRequestHandler, HTTPServer
import json

class Handler(BaseHTTPRequestHandler):
    def do_GET(self):
        body = json.dumps({"name": "tea", "id": 1}).encode()
        self.send_response(200)
        self.send_header("Content-Type", "application/json")
        self.end_headers()
        self.wfile.write(body)

    def do_POST(self):
        body = self.rfile.read(int(self.headers.get("Content-Length", 0)))
        try:
            data = json.loads(body)
        except ValueError:
            self.send_error(400)
            return
        result = json.dumps({"received": data}).encode()
        self.send_response(201)
        self.send_header("Content-Type", "application/json")
        self.end_headers()
        self.wfile.write(result)

HTTPServer(("127.0.0.1", 18766), Handler).serve_forever()

Run python3 server.py in a terminal and leave it running. Open another terminal for the curl commands below. The address 127.0.0.1 points to your own machine. This toy service returns the same item for any GET path and echoes JSON sent to any POST path; it does not save anything.

API performance problems fall into two categories: the ones that appear immediately during development and are fixed before they matter, and the ones that are invisible during development and catastrophic at production scale. The second category is where the interesting work is. Understanding where APIs slow down under load — and the specific techniques that address each cause — is the difference between an API that performs at scale and one that requires emergency remediation after launch.

APIs are contracts. When you publish an API and someone builds an integration against it, they are betting their system on your endpoint continuing to behave as documented. Versioning is how you preserve that contract while still being able to evolve the underlying system. Done well, it gives you forward momentum without leaving integrators behind. Done poorly, it creates a maintenance burden that accumulates until one side gives up.

What Counts as a Breaking Change

The most important skill in API versioning is recognizing what requires a version increment. A breaking change is anything that causes a previously valid, working integration to fail or behave differently without modification. This is a broader category than most developers initially assume.

HTTP is a synchronous protocol. A client sends a request and waits for a response. This works well for operations that complete in milliseconds — a database read, a record update, a validation check. It breaks down for operations that take seconds, minutes, or longer: video transcoding, report generation, bulk data exports, machine learning inference on large inputs, email campaigns to millions of recipients.

Holding an HTTP connection open for a minute or more is technically possible and practically wrong. Clients time out. Load balancers have maximum request durations. Users cannot tell the difference between a server still working and a server that silently failed. Long synchronous operations produce brittle integrations and poor user experiences.

HTTP was designed from the beginning to support multiple representations of the same resource. A user profile can be represented as JSON for a machine consumer or as HTML for a browser. A dataset can be returned as JSON or as CSV depending on what the client intends to do with it. An image can be served as JPEG or WebP based on what the browser supports. Content negotiation is the mechanism through which clients and servers agree on which representation to use — and understanding it is essential for building APIs that serve diverse consumers cleanly.

CORS is the source of more developer frustration than almost any other browser security mechanism — not because it is poorly designed, but because its error messages are opaque, its rules are non-obvious, and it only manifests in a specific context that server-side developers often do not encounter during development. Understanding what CORS actually is and why it exists transforms it from an arbitrary obstacle into a predictable system with clear rules.

File handling is where many otherwise well-designed APIs cut corners. The result is integrations that work fine for small files and break under production conditions: uploads timing out on slow connections, downloads failing midway through large transfers, clients with no way to resume an interrupted operation. File upload and download have well-established patterns that handle these conditions correctly. Most of them require explicit design choices rather than the defaults.

Simple Upload: When It Is Sufficient

For files under a few megabytes that users upload infrequently, a direct multipart form upload to your API is the simplest approach. The client sends a multipart/form-data POST request with the file as one part and any metadata as additional parts or as a separate JSON field:

Caching is one of the highest-leverage performance improvements available to an API, and one of the least consistently implemented. A response that is cached at the right layer — in a CDN, a reverse proxy, or the client itself — eliminates a server round trip entirely. At scale, that elimination compounds: fewer database queries, lower infrastructure cost, faster responses for every consumer. The HTTP specification provides a complete, standardized caching system. Most APIs use it only partially, leaving significant headroom unrealized.

Networks fail. Connections drop. Load balancers time out. Servers restart mid-request. In a distributed system, any request that travels over a network can be sent but not confirmed, leaving the caller uncertain whether the operation completed. This is not a rare edge case — it is a routine condition that well-designed APIs must handle. Idempotency is the mechanism that makes retrying safe when certainty is unavailable.

What Idempotency Means

An operation is idempotent if performing it multiple times produces the same result as performing it once. The outcome is identical whether you call it one time or ten times; subsequent calls do not change anything that the first call already changed.

An API’s data contract — what it accepts as input, what it returns as output — exists whether you define it formally or not. Leaving it informal means the contract lives only in documentation prose and developer intuition, is inconsistently enforced, and drifts between what the documentation says and what the code actually handles. JSON Schema provides a standard, machine-readable format for expressing data contracts that can drive validation, documentation, and testing from a single source of truth.

Istio 1.31 is out, and one line in the release notes says a lot about where API infrastructure is heading. You can now run agentgateway, a proxy built for AI agent and MCP traffic, as a waypoint inside the mesh.

If “waypoint” means nothing to you yet, that’s fine. Here’s the short version, then why it matters if you build APIs.

What changed in 1.31

Istio’s ambient mode splits the mesh in two. A small per-node component handles encryption and basic connectivity. Anything that needs to understand HTTP, like routing, auth policy or rate limits, goes through a separate proxy called a waypoint. You opt services into a waypoint with a label.

OpenAI’s DevDay last week was mostly pitched as an agents event. Persistent agents, cloud Codex, a cheaper model. Fine. But if you’re learning to build and design APIs, two of the smaller releases are worth more of your attention than the headline model, because they say a lot about where API contracts are going.

Here’s what shipped, then what to take from it.

What OpenAI released

The Agents API is now in public beta. It runs agents on OpenAI’s own infrastructure, with memory, tool calling, tool search, context compaction and multi-agent support carried over from Codex. The new piece is computer use: an agent can now drive software through its graphical interface, clicking and typing the way a person would.

Every few weeks someone asks whether MCP replaces REST. It does not. The question is still worth answering carefully, because the line between the two moved in July, and most of the explanations written before then are now describing a protocol that no longer exists.

An HTTP API is a contract between two pieces of software written by people who read documentation. A developer opens the reference, learns that POST /v1/invoices wants a customer ID and an array of line items, writes the call, and ships it. The knowledge lived in a human head at build time and then got frozen into source code. When the endpoint changes, something breaks in production and a person goes and fixes it.

APIs designed for desktop web clients on reliable broadband do not perform well on mobile without deliberate adaptation. Mobile clients operate under constraints that server-side developers often underestimate: variable and often poor network conditions, limited battery budgets where every radio transmission costs energy, smaller screens that need different data shapes than desktop, and the expectation of usable offline states that desktop web apps rarely require. Building an API that serves mobile clients well requires understanding these constraints and making design decisions that account for them.

Authentication is where most API integrations go wrong the first time. Not because the concepts are complicated, but because there are several distinct mechanisms in common use, they solve different problems, and developers often reach for the one they recognize rather than the one that fits. Understanding what each mechanism actually does — and what it does not do — is the difference between an integration that works and one that works until it doesn’t.

APIs that external developers pay to use require more than good technical design. They require a pricing model that aligns cost with value, metering infrastructure that accurately tracks usage, and billing systems that translate usage into charges reliably. These are product and engineering concerns that compound — a poorly designed pricing model produces integrators who spend more time managing API costs than building their product, and metering infrastructure that loses events produces disputes and lost revenue.

An API that works in development and fails in production in ways you cannot diagnose is worse than an API that fails loudly. Production is where assumptions meet reality, and the gap between them only becomes visible if you can see what is happening inside the system. Observability is the discipline of making distributed systems understandable — building in enough visibility that when something goes wrong, you can find out what, where, and why without guessing.

OpenAI’s DevDay last week was mostly pitched as an agents event. Persistent agents, cloud Codex, a cheaper model. Fine. But if you’re learning to build and design APIs, two of the smaller releases are worth more of your attention than the headline model, because they say a lot about where API contracts are going.

Here’s what shipped, then what to take from it.

What OpenAI released

The Agents API is now in public beta. It runs agents on OpenAI’s own infrastructure, with memory, tool calling, tool search, context compaction and multi-agent support carried over from Codex. The new piece is computer use: an agent can now drive software through its graphical interface, clicking and typing the way a person would.

An API’s data contract — what it accepts as input, what it returns as output — exists whether you define it formally or not. Leaving it informal means the contract lives only in documentation prose and developer intuition, is inconsistently enforced, and drifts between what the documentation says and what the code actually handles. JSON Schema provides a standard, machine-readable format for expressing data contracts that can drive validation, documentation, and testing from a single source of truth.

Documentation is the first thing a developer encounters and the last thing most teams prioritize. The result is a familiar pattern: the API is built, the launch deadline approaches, documentation gets written in a hurry by someone who did not build the API and does not fully understand it, and integrators spend the next six months filing support tickets that could have been answered by better documentation. OpenAPI exists to break that cycle by making documentation a first-class artifact of the API itself.

Returning a list of items from an API sounds simple until the list has ten thousand items. At that point, the response is too large to transfer efficiently, too slow to serialize, and too expensive to compute. Pagination is how APIs break large result sets into manageable chunks that clients can fetch incrementally. Choosing the wrong pagination pattern — or implementing the right one incorrectly — creates problems that do not appear until production load reveals them.

An API that works in development and fails in production in ways you cannot diagnose is worse than an API that fails loudly. Production is where assumptions meet reality, and the gap between them only becomes visible if you can see what is happening inside the system. Observability is the discipline of making distributed systems understandable — building in enough visibility that when something goes wrong, you can find out what, where, and why without guessing.

Returning a list of items from an API sounds simple until the list has ten thousand items. At that point, the response is too large to transfer efficiently, too slow to serialize, and too expensive to compute. Pagination is how APIs break large result sets into manageable chunks that clients can fetch incrementally. Choosing the wrong pagination pattern — or implementing the right one incorrectly — creates problems that do not appear until production load reveals them.

API performance problems fall into two categories: the ones that appear immediately during development and are fixed before they matter, and the ones that are invisible during development and catastrophic at production scale. The second category is where the interesting work is. Understanding where APIs slow down under load — and the specific techniques that address each cause — is the difference between an API that performs at scale and one that requires emergency remediation after launch.

Testing an API is not the same as testing a library or a UI. An API is a contract — a public interface that other systems depend on — and the testing strategy must reflect that. Unit tests tell you whether individual functions work. Integration tests tell you whether the system behaves correctly end to end. Contract tests tell you whether the API still honors its published interface. Load tests tell you when it breaks. All four serve distinct purposes and none is a substitute for the others.

The standard REST pattern is one resource per request. Create one user, update one order, fetch one product. This works until an integrator needs to create ten thousand users, update five hundred orders, or sync an entire product catalog. Making ten thousand individual API calls is slow, expensive in terms of rate limit quota, and brittle — a network failure on request 7,432 leaves the integrator with a partially completed operation and no clean recovery path.

APIs designed for desktop web clients on reliable broadband do not perform well on mobile without deliberate adaptation. Mobile clients operate under constraints that server-side developers often underestimate: variable and often poor network conditions, limited battery budgets where every radio transmission costs energy, smaller screens that need different data shapes than desktop, and the expectation of usable offline states that desktop web apps rarely require. Building an API that serves mobile clients well requires understanding these constraints and making design decisions that account for them.

Caching is one of the highest-leverage performance improvements available to an API, and one of the least consistently implemented. A response that is cached at the right layer — in a CDN, a reverse proxy, or the client itself — eliminates a server round trip entirely. At scale, that elimination compounds: fewer database queries, lower infrastructure cost, faster responses for every consumer. The HTTP specification provides a complete, standardized caching system. Most APIs use it only partially, leaving significant headroom unrealized.

Rate limiting is one of those features that looks optional until the moment it becomes mandatory. Without it, a single misbehaving client — a misconfigured retry loop, a runaway script, a bad actor — can degrade or take down your API for every other consumer. With it, you define the boundaries of acceptable usage and enforce them automatically. For any API exposed to more than one consumer, rate limiting is infrastructure, not a feature.

Sixty-six sites, 18,880 visits and 19,950 page views for the week of August 30 to September 5. Visits rose 14.91% and page views 17.01%, which is a good week by any reading of the top line. The median page load time across the network went the other way, climbing 28.64% to 3,579ms, and that single figure complicates the rest of the report.

technologies.org led again with 2.44k visits and 2.52k page views, up 74.29% and 76.22% respectively, on a load time of 2,561ms (up 8.8%). Chrome accounted for 1.32k of those sessions against 1.05k logged as Unknown, with a further 30 from ChromeMobileWebview. Its LCP at the 75th percentile improved by a third to 2,704ms even as the raw load time crept up, so the main content is painting faster while the tail of the load stretches out. CLS came in at 1, up 262.32%, and INP at 40ms. In second place, marketresearchmedia.com posted 1.17k visits and 1.17k page views, both up 265.62%, making it the largest mover in the report and also its worst performer on speed: load time nearly tripled to 7,454ms and the 75th percentile LCP went up almost fivefold to 4,988ms. Chrome carried 1.02k of those sessions, Unknown 110, ChromeMobile 10. Visits and page views are identical, so every session ended on the page it began on. Third, analysis.org held steady at 1.1k visits (up 8.91%) and 1.12k page views (up 9.8%), and delivered the clearest genuine improvement in the report with a load time down 21.99% to 3,579ms after weeks in five figures. Its LCP eased 10.42% to 3,680ms, CLS sat flat at 1, INP at 40ms. Unusually for the top three, Unknown outnumbered Chrome here, 660 to 390, with 20 on ChromeMobile.

An API gateway is a server that sits between clients and backend services, acting as the single entry point through which all API traffic passes. Every request goes through the gateway, which can inspect, modify, authenticate, route, transform, and rate-limit that traffic before it reaches any backend service. For teams running multiple services, an API gateway centralizes concerns that would otherwise be duplicated across every service independently.

Understanding what a gateway provides — and what it does not — is the prerequisite to deciding whether one belongs in your architecture.

API security failures are not exotic. They rarely involve sophisticated attacks on cryptographic primitives or novel zero-day exploits. The most consequential breaches — the ones that expose millions of records, compromise user accounts, or shut down services — happen because an API allowed something it should not have, at a scale its designers did not anticipate. Understanding the fundamental attack surface of an API and designing against it deliberately is the entire discipline. It is not advanced knowledge. It is the baseline.

Rate limiting is one of those features that looks optional until the moment it becomes mandatory. Without it, a single misbehaving client — a misconfigured retry loop, a runaway script, a bad actor — can degrade or take down your API for every other consumer. With it, you define the boundaries of acceptable usage and enforce them automatically. For any API exposed to more than one consumer, rate limiting is infrastructure, not a feature.

Standard HTTP is a request-response protocol: the client sends a request, the server sends a response, the connection closes or is returned to a pool. This model is efficient for most API use cases. It is the wrong model when the server needs to push data to the client without waiting for a client request — live dashboards, chat applications, collaborative editing, real-time notifications, trading feeds. Three patterns exist to bridge this gap, each with a different complexity profile and a different set of constraints.

Every integration eventually confronts the same question: how does my system learn that something changed in someone else’s system? The two answers are polling and webhooks. Polling asks the question repeatedly. Webhooks get notified when the answer changes. Understanding which approach fits a given situation — and why — shapes everything from latency and cost to reliability and operational complexity.

Polling: The Default That Mostly Works

Polling is the simpler mental model. Your application sends requests to an API on a schedule — every 30 seconds, every minute, every hour — and checks whether anything has changed since the last check. If yes, process the changes. If no, wait for the next interval.

The curl lesson showed what an API exchange looks like by hand. This one moves the same work into Python with the requests library. By the end you’ll have a small client function that sets a timeout on every call, reuses one connection, and turns every way a call can fail into one clear error your code can act on.

You need Python 3.10 or newer, which is the minimum for the current requests release (2.34.2). Everything runs against a test server on your own machine, so no account or API key is involved.

Errors are not edge cases in API development. They are a primary output. Every API call that can fail will fail — due to invalid input, authentication problems, resource conflicts, rate limits, or infrastructure issues — and how an API communicates those failures determines whether integrators can handle them gracefully or are left guessing. An API that returns clear, consistent, actionable errors is a well-designed API. Everything else is guesswork at scale.

The standard REST pattern is one resource per request. Create one user, update one order, fetch one product. This works until an integrator needs to create ten thousand users, update five hundred orders, or sync an entire product catalog. Making ten thousand individual API calls is slow, expensive in terms of rate limit quota, and brittle — a network failure on request 7,432 leaves the integrator with a partially completed operation and no clean recovery path.

Networks fail. Connections drop. Load balancers time out. Servers restart mid-request. In a distributed system, any request that travels over a network can be sent but not confirmed, leaving the caller uncertain whether the operation completed. This is not a rare edge case — it is a routine condition that well-designed APIs must handle. Idempotency is the mechanism that makes retrying safe when certainty is unavailable.

What Idempotency Means

An operation is idempotent if performing it multiple times produces the same result as performing it once. The outcome is identical whether you call it one time or ten times; subsequent calls do not change anything that the first call already changed.

GraphQL shifts the design work from endpoint definition to schema design. The schema is the API — every type, field, query, and mutation is declared in the schema, and the schema governs everything the API can do. Designing a GraphQL schema well requires understanding how types compose, how to express mutations that reflect real domain operations, and where GraphQL’s conventions differ meaningfully from REST patterns that GraphQL developers often import by habit.

REST APIs organize their surface around resources — the nouns of your domain. How you identify, name, and structure those resources determines whether your API feels intuitive or requires constant documentation reference. Good URL design is not aesthetic preference. It is communication: URLs tell developers what the API contains, how it is organized, and how to navigate it. Done well, a developer can infer what endpoints exist from the ones they already know.

Returning a list of items from an API sounds simple until the list has ten thousand items. At that point, the response is too large to transfer efficiently, too slow to serialize, and too expensive to compute. Pagination is how APIs break large result sets into manageable chunks that clients can fetch incrementally. Choosing the wrong pagination pattern — or implementing the right one incorrectly — creates problems that do not appear until production load reveals them.

REST APIs organize their surface around resources — the nouns of your domain. How you identify, name, and structure those resources determines whether your API feels intuitive or requires constant documentation reference. Good URL design is not aesthetic preference. It is communication: URLs tell developers what the API contains, how it is organized, and how to navigate it. Done well, a developer can infer what endpoints exist from the ones they already know.

Every API starts with a choice that will shape every decision that follows: what protocol are you building on? REST, GraphQL, and gRPC are the three dominant options in modern API development, and none of them is universally correct. Each reflects a different set of assumptions about who is calling the API, how often, and what they need back.

Understanding the tradeoffs is not optional knowledge for serious API developers. It is the foundation.

Testing an API is not the same as testing a library or a UI. An API is a contract — a public interface that other systems depend on — and the testing strategy must reflect that. Unit tests tell you whether individual functions work. Integration tests tell you whether the system behaves correctly end to end. Contract tests tell you whether the API still honors its published interface. Load tests tell you when it breaks. All four serve distinct purposes and none is a substitute for the others.

GraphQL shifts the design work from endpoint definition to schema design. The schema is the API — every type, field, query, and mutation is declared in the schema, and the schema governs everything the API can do. Designing a GraphQL schema well requires understanding how types compose, how to express mutations that reflect real domain operations, and where GraphQL’s conventions differ meaningfully from REST patterns that GraphQL developers often import by habit.

An API’s data contract — what it accepts as input, what it returns as output — exists whether you define it formally or not. Leaving it informal means the contract lives only in documentation prose and developer intuition, is inconsistently enforced, and drifts between what the documentation says and what the code actually handles. JSON Schema provides a standard, machine-readable format for expressing data contracts that can drive validation, documentation, and testing from a single source of truth.

Documentation is the first thing a developer encounters and the last thing most teams prioritize. The result is a familiar pattern: the API is built, the launch deadline approaches, documentation gets written in a hurry by someone who did not build the API and does not fully understand it, and integrators spend the next six months filing support tickets that could have been answered by better documentation. OpenAPI exists to break that cycle by making documentation a first-class artifact of the API itself.

Sixty-six sites, 18,880 visits and 19,950 page views for the week of August 30 to September 5. Visits rose 14.91% and page views 17.01%, which is a good week by any reading of the top line. The median page load time across the network went the other way, climbing 28.64% to 3,579ms, and that single figure complicates the rest of the report.

technologies.org led again with 2.44k visits and 2.52k page views, up 74.29% and 76.22% respectively, on a load time of 2,561ms (up 8.8%). Chrome accounted for 1.32k of those sessions against 1.05k logged as Unknown, with a further 30 from ChromeMobileWebview. Its LCP at the 75th percentile improved by a third to 2,704ms even as the raw load time crept up, so the main content is painting faster while the tail of the load stretches out. CLS came in at 1, up 262.32%, and INP at 40ms. In second place, marketresearchmedia.com posted 1.17k visits and 1.17k page views, both up 265.62%, making it the largest mover in the report and also its worst performer on speed: load time nearly tripled to 7,454ms and the 75th percentile LCP went up almost fivefold to 4,988ms. Chrome carried 1.02k of those sessions, Unknown 110, ChromeMobile 10. Visits and page views are identical, so every session ended on the page it began on. Third, analysis.org held steady at 1.1k visits (up 8.91%) and 1.12k page views (up 9.8%), and delivered the clearest genuine improvement in the report with a load time down 21.99% to 3,579ms after weeks in five figures. Its LCP eased 10.42% to 3,680ms, CLS sat flat at 1, INP at 40ms. Unusually for the top three, Unknown outnumbered Chrome here, 660 to 390, with 20 on ChromeMobile.

Every API feature eventually reaches the end of its useful life. The endpoint was designed before the domain was understood. The schema made assumptions that no longer hold. A better approach exists. The old version must go. How you handle that retirement determines whether your API’s integrators trust you or resent you.

Deprecation done well is a communication and scheduling problem. Deprecation done poorly is a breaking change that happens without warning.

APIs are contracts. When you publish an API and someone builds an integration against it, they are betting their system on your endpoint continuing to behave as documented. Versioning is how you preserve that contract while still being able to evolve the underlying system. Done well, it gives you forward momentum without leaving integrators behind. Done poorly, it creates a maintenance burden that accumulates until one side gives up.

What Counts as a Breaking Change

The most important skill in API versioning is recognizing what requires a version increment. A breaking change is anything that causes a previously valid, working integration to fail or behave differently without modification. This is a broader category than most developers initially assume.

HTTP was designed from the beginning to support multiple representations of the same resource. A user profile can be represented as JSON for a machine consumer or as HTML for a browser. A dataset can be returned as JSON or as CSV depending on what the client intends to do with it. An image can be served as JPEG or WebP based on what the browser supports. Content negotiation is the mechanism through which clients and servers agree on which representation to use — and understanding it is essential for building APIs that serve diverse consumers cleanly.

HTTP is a synchronous protocol. A client sends a request and waits for a response. This works well for operations that complete in milliseconds — a database read, a record update, a validation check. It breaks down for operations that take seconds, minutes, or longer: video transcoding, report generation, bulk data exports, machine learning inference on large inputs, email campaigns to millions of recipients.

Holding an HTTP connection open for a minute or more is technically possible and practically wrong. Clients time out. Load balancers have maximum request durations. Users cannot tell the difference between a server still working and a server that silently failed. Long synchronous operations produce brittle integrations and poor user experiences.

Every integration eventually confronts the same question: how does my system learn that something changed in someone else’s system? The two answers are polling and webhooks. Polling asks the question repeatedly. Webhooks get notified when the answer changes. Understanding which approach fits a given situation — and why — shapes everything from latency and cost to reliability and operational complexity.

Polling: The Default That Mostly Works

Polling is the simpler mental model. Your application sends requests to an API on a schedule — every 30 seconds, every minute, every hour — and checks whether anything has changed since the last check. If yes, process the changes. If no, wait for the next interval.

Standard HTTP is a request-response protocol: the client sends a request, the server sends a response, the connection closes or is returned to a pool. This model is efficient for most API use cases. It is the wrong model when the server needs to push data to the client without waiting for a client request — live dashboards, chat applications, collaborative editing, real-time notifications, trading feeds. Three patterns exist to bridge this gap, each with a different complexity profile and a different set of constraints.

Sixty-six sites, 18,880 visits and 19,950 page views for the week of August 30 to September 5. Visits rose 14.91% and page views 17.01%, which is a good week by any reading of the top line. The median page load time across the network went the other way, climbing 28.64% to 3,579ms, and that single figure complicates the rest of the report.

technologies.org led again with 2.44k visits and 2.52k page views, up 74.29% and 76.22% respectively, on a load time of 2,561ms (up 8.8%). Chrome accounted for 1.32k of those sessions against 1.05k logged as Unknown, with a further 30 from ChromeMobileWebview. Its LCP at the 75th percentile improved by a third to 2,704ms even as the raw load time crept up, so the main content is painting faster while the tail of the load stretches out. CLS came in at 1, up 262.32%, and INP at 40ms. In second place, marketresearchmedia.com posted 1.17k visits and 1.17k page views, both up 265.62%, making it the largest mover in the report and also its worst performer on speed: load time nearly tripled to 7,454ms and the 75th percentile LCP went up almost fivefold to 4,988ms. Chrome carried 1.02k of those sessions, Unknown 110, ChromeMobile 10. Visits and page views are identical, so every session ended on the page it began on. Third, analysis.org held steady at 1.1k visits (up 8.91%) and 1.12k page views (up 9.8%), and delivered the clearest genuine improvement in the report with a load time down 21.99% to 3,579ms after weeks in five figures. Its LCP eased 10.42% to 3,680ms, CLS sat flat at 1, INP at 40ms. Unusually for the top three, Unknown outnumbered Chrome here, 660 to 390, with 20 on ChromeMobile.