Every one of these questions is one I have actually been asked — in a workshop, on a call, in an email, or by someone standing at the front of a room after a talk. The answers come out of sixteen years of writing about APIs at API Evangelist, the guidance catalog, the papers, and the machine-readable evidence behind apis.io.
They are opinionated. That is the point — a FAQ that refuses to take a position is just a glossary.
136 questions shown. Full search →
Yes — submit it through the add-API form on APIs.io, or open a request. The listing gets built from what your public surface actually returns, so publishing your artifacts first gets you a better profile.
The Supreme Court's 2021 decision in Google v. Oracle found Google's reimplementation of the Java API to be fair use — protecting the freedom to build compatible systems, without settling every underlying question.
Yes to both. The change log is the single most revealing artifact an API provider publishes, and a public road map converts a dependency relationship into a partnership.
You need the things a portal provides — docs, signup, keys, plans, support, status, change log — in one findable place. Whether that is a product or a static site matters far less than whether it exists and is current.
Yes, if anyone builds on your API. And it needs to reflect reality quickly and honestly — a status page that stays green through an outage costs more trust than having none at all.
Yes — it is where governance starts, because you cannot govern toward a standard you have not written down. But a style guide that is not connected to machine-enforced rules will not change behavior.
Once more than one API or more than one consumer exists, yes — a gateway is where authentication, rate limiting, routing and observability get applied consistently instead of reimplemented per service.
It is cheap and harmless, and it can help machine consumers orient. It is not a substitute for a precise OpenAPI, and nothing enforces what it says — treat it as a signpost, not a control.
The best ones are genuinely excellent and the average is poor — and the difference is almost always sustained funding and a named owner rather than technology or intent.
No. Plenty of the most valuable APIs generate zero direct revenue and earn their keep through adoption, integration, cost avoidance, or partner reach — but you should be able to say which of those it is.
They turn compliance from a periodic manual audit scramble into a continuous, observable, automatable property — if you encode the requirements as governance rules and keep the evidence machine-readable.
Keep your definitions, rules and collections in open formats in your own repositories, buy vendors for execution rather than for storage of your truth, and know your exit before you sign.
Announce early with a firm date, publish a deprecation policy before you need it, contact affected consumers individually using your own usage data, provide a migration path, and never sunset quietly.
Be predictable, be transparent about pricing and limits and status, communicate change early, honor deprecation commitments, and do not compete with the people building on you.
Triangulate — gateway configs, DNS and certificates, code repositories, cloud accounts, traffic logs, and asking people. No single source is complete, and the ones nobody claims are the ones that matter most.
Ask them directly, make the channels visible and machine-readable, and — most importantly — visibly act on what you hear. A feedback loop where nothing ever changes stops receiving feedback.
Ask, and it happens. The default outcome keeps a name, a description and a link to your own site, with no rating and no artifacts — and there is a permanent registry that stops you being re-added.
Make one real call to somebody else's API before you design your own — then design your first API around what a consumer needs, not around your database.
Put the feedback where they already work, explain the why with every rule, allow exceptions through a real process, and roll out by team or domain rather than all at once.
Hold every protocol to the same set of obligations — machine-readable contract, named owner, security model, versioning policy, catalog entry — while using each one's native contract format to enforce them.
Hold them to the same obligations as your HTTP APIs — contracts, ownership, discovery, versioning, security, observability — using AsyncAPI and schema registries as the enforcement surface.
Generate everything you can from the contract, keep the prose in version control next to the code, and test the examples in CI. Documentation maintained separately from the API will always drift.
Publish machine-readable pointers on your own domain — an OpenAPI at a stable URL, an APIs.json index, an llms.txt — get listed where people already look, and make sure a search engine can read your docs.
Define the policy once in a vendor-neutral form, generate or verify each gateway's configuration from it, and report coverage across all of them. Hand-maintaining parallel policy sets never stays in sync.
Count consumption and outcomes, not endpoints and signups. Active integrations, calls that succeed, time to first call, and value delivered downstream — an API has no value until it is actually used.
Generate a mock from your OpenAPI document and hand it to consumers on day one. It turns the contract into something people can react to before the cost of change goes up.
Start from the value exchange, not the price list. Direct billing is only one model — many of the most successful API programs earn nothing from the API itself and everything from the business it enables.
Use the language the business uses, plural nouns for collections, consistent casing everywhere, and no abbreviations that require a decoder ring. Then write the convention down and lint it.
Fix the causes rather than scaling the answering — better errors, better onboarding, documented edge cases, and public answers that search can find. Then treat support as a signal about your design.
Set them per consumer and per plan rather than globally, publish them, return them in headers, give people a path to more, and remember rate limits are a business tool as much as a protective one.
Assume they will leak. Scope them narrowly, expire them by default, make rotation and revocation trivial, scan your repositories continuously, and monitor for anomalous use.
Make the contract executable in your pipeline. Lint the definition on every change, run contract tests against the live API, and fail the build when the two disagree. Drift is a process problem, not a discipline problem.
Treat the tool name and description as the contract. There is no version negotiation in the protocol, so renaming a tool or rewriting its description is a breaking change even when your HTTP API did not move.
As fast as you can without accumulating debt your consumers pay for. Governance is not the enemy of velocity — ungoverned speed is what eventually stops you shipping at all.
From what you publish publicly. You improve it by publishing the things you are missing — a real OpenAPI, schema, plans, limits, security, a change log — and you can see exactly which checks you are failing.
The wrong question. Ask instead how many you already have, who owns each one, and how many of them anybody actually uses — most organizations cannot answer any of the three.
There is no single right answer — containers, serverless, gateways, managed platforms and database-generated APIs all deploy real APIs. Pick for your team's operational reality, and make the deployment path repeatable...
Pick one strategy — cursor-based for large or changing datasets, offset for small stable ones — apply it identically across every collection, and document the contract including what happens when data changes mid-pagi...
Use the right HTTP status code, return a consistent machine-readable error body across every endpoint, include something the consumer can act on, and document every error in your contract.
Publish the price. Align it to the value the consumer receives rather than to your infrastructure cost, keep the units something they can predict, and make it comparable without a sales call.
Define what elevated access buys and what it requires, give partners a named human and early notice of change, and treat the tier as a business relationship rather than a bigger rate limit.
Layer it — TLS everywhere, real authentication, least-privilege authorization, input validation from schema, rate limiting, logging and monitoring — and enforce the baseline with governance rules rather than good inte...
Independent. There is no vendor sponsorship of the research, the rubric is public and versioned, and API Evangelist's own properties get scored under the same rules as everyone else.
No. It lost the center of gravity to REST and it is still running in production across most large enterprises. Treating it as merely obsolete is both inaccurate and a mistake.
Probably not, by the strict definition — and it almost certainly does not matter. Aim for consistent and usable, not doctrinally pure.
Adopt the standard unless you have a specific, articulable reason not to. Every standard you adopt is a set of decisions you do not have to make and tooling you do not have to build.
Generate them from your OpenAPI for the two or three languages your consumers actually use, and only hand-craft where the generated experience is genuinely bad. A good OpenAPI and good docs beat six neglected SDKs.
Only if you have a genuine need for independent scaling and deployment, and the organizational discipline to decouple the teams as well as the code. Otherwise you get a distributed monolith with extra operational cost.
Often yes — but assume the terms will change. Read them, know your migration path, avoid depending on a single provider for anything existential, and price the dependency honestly.
Either is fine as long as the result is accurate, reviewed, and version-controlled. Generated specs drift toward describing whatever the code happens to do, rather than what you promised.
Generate it from the OpenAPI, yes — but curate what becomes a tool. Three hundred endpoints turned into three hundred tools produces an unusable agent surface.
List where your buyers already procure — the cloud marketplaces are the ones that reliably move real money. Treat marketplaces as a channel, not as a substitute for your own developer experience.
Log enough to reconstruct what happened, never log credentials or personal data you do not need, and decide retention deliberately — because an access log is also a surveillance record.
If businesses depend on you, yes — and offer an honest one you can measure and will actually honor. An SLA is where reliability stops being a vague promise and becomes a commitment.
URL versioning is the pragmatic default — visible, cacheable, debuggable, and understood by everyone. Header-based versioning is purer and consistently harder to operate.
The discipline is right — an owner, a road map, consumers, a lifecycle. But be honest about whether your leadership actually treats it as one, because "API product" is often a framing nobody above you has bought.
Vacuum runs Spectral rulesets, is dramatically faster, and adds rule metadata like IDs, categories and how-to-fix text. Start wherever your tooling already is — but the speed is what lets governance run everywhere rat...
Yes. Git is the factory floor of API operations — definitions in version control, changes proposed through pull requests, governance running on every commit, history attributed and timestamped.
Offer enough free access for someone to evaluate you properly without talking to anyone. Whether it stays free forever is a business decision; whether evaluation is self-service is not.
Get in touch with the specific URLs. Every claim gets checked against a live fetch, and where the evidence supports a correction it gets made and the provider gets rescored.
A plan is the whole package a class of consumer gets — endpoints, limits, support, terms, price — not just a price point. Structure them around distinct consumer types you can actually name.
Scopes define what a token may do. Design them around what a consumer is trying to accomplish, publish them as a first-class page, and reference them inline in your documentation.
Applying targeted modifications to an OpenAPI document without altering the source — adding examples, translating descriptions, injecting governance metadata, or specializing for one audience. Keep the base pristine a...
A skill is a packaged, self-describing unit of what you let someone accomplish. It is the same question I have been asking since 2016 — what does your API actually let me do — with a new name and, finally, an audience...
Research reports built from the catalog's machine-readable evidence. $25 topic papers, $500 Sector and Standard Reports, $750 Portfolio Reports, and deeper enterprise bundles.
Validate the definition, lint it against your rules, diff it for breaking changes, run contract tests against the deployed API, and publish the artifacts. Everything else is optional; those five are not.
That machine-to-machine commerce is decades older than the web API, that standards plus trading-partner relationships can outlast every fashion, and that the API economy is much earlier in its life than we like to think.
Anything that makes a previously working consumer stop working — removing or renaming fields, tightening validation, changing types or defaults, or altering error behavior. Detect it mechanically by diffing the contract.
A precise machine-readable contract, clean schema, task-shaped capabilities, honest descriptions, documented errors and limits, and a way for a machine to discover all of it. It is the API discipline you already knew,...
Almost nothing, on its own. It might mean publicly documented, freely accessible, openly licensed, or merely "we have an API." Ask which one they mean, because the differences are the whole story.
Free reading and checking — the blog, guidance, catalogs, and APIs.io discovery. Paid research reports, and paid work: profiling, scoring, governance and agent-readiness engagements.
More than the governance would. The cost shows up as duplicated build effort, slow integration and onboarding, breakages, security exposure from APIs nobody knows about, and maintenance on services no one uses.
REST is an architectural style that uses HTTP the way it was designed — resources at URLs, standard methods, standard status codes — and in practice "REST" has become a loose label for "a normal HTTP API."
Deciding what data you expose, to whom, on what basis, and for how long — and being able to prove it. Data minimization is the single most effective privacy control, and almost nobody applies it.
It documented the birth of the API economy, grew to thousands of hand-curated listings, and shut down in 2022 — which tells you that manual curation cannot keep pace and that directories are hard to sustain.
The research, writing, and catalog work I have been doing since 2010 — a blog, a network of catalogs and specifications, a rating system, a search engine at APIs.io, and a set of paid research reports.
Design-first means the machine-readable contract exists and is agreed before the implementation is built. It is worth it — but you will not convince everyone, and the realistic goal is a contract that is authoritative...
Carrying a message you believe in to people who have not heard it, patiently and repeatedly, until they can act on it. It is mostly storytelling, and it is as much internal as external.
Everything an organization does to make its APIs consistent, discoverable, safe and supportable — from a written style guide through automated linting to who is accountable when it goes wrong.
Linting runs machine-executable rules against your API definitions. Start with validity, security schemes, descriptions and naming — and remember that a green check is the visible part of governance, not the whole of it.
API management is the operational layer that turns an endpoint into a business — identity, plans, rate limits, analytics, and a portal. You need the capabilities; whether you buy one platform or assemble them is a sep...
The search engine over the API Evangelist catalog — thousands of providers and their APIs, with their artifacts, ratings, and machine-readable properties, searchable by humans and by agents.
A machine-readable index a provider publishes on their own domain, describing their APIs and everything around them — docs, OpenAPI, terms, pricing, support. A sitemap for APIs, and decentralized discovery by design.
Arazzo is the OpenAPI Initiative specification for describing multi-step API workflows. You need it when the outcome your consumers want takes more than one call — which is nearly always.
AsyncAPI is the machine-readable contract for event-driven and message-driven APIs — the OpenAPI of the asynchronous world. You need it the moment you have a Kafka topic, a queue, or a webhook that consumers depend on.
JSON Schema describes and validates the structure of your data. It matters because it is what OpenAPI is built out of, and because schema drift is the most expensive and most preventable form of API decay.
JSON-LD adds shared meaning to JSON by linking fields to common vocabularies. Adoption has been frustratingly thin — but machine consumers that must interpret data without a human in the loop are the case it was built...
Model Context Protocol is how AI agents discover and call tools. You need one if you want agents to use your API reliably — but generating it blindly from a large OpenAPI is a mistake.
A capability is a human- and machine-readable definition of something the business can do. The test is that it has to matter to technical and non-technical stakeholders alike — which "API" usually does not.
A token a user can generate for their own account without registering an application. Yes, you should offer one — it removes the single biggest source of onboarding friction in OAuth-based APIs.
An API key identifies the caller so you can meter, track and control them. On its own it provides very little security, and treating it as a fortress is one of the oldest mistakes in this space.
An API strategy is a written statement of which business capabilities you are exposing, to whom, why, and how you will support them. Even a two-person team needs the one-page version.
An API is a contract that lets one piece of software ask another piece of software for something over a network, in a predictable, documented way.
OpenAPI is a machine-readable description of your HTTP API. You need one because it is what documentation, mocks, tests, SDKs, gateways, governance and AI tooling are all generated from.
OAuth gives you the mechanics of consent, not the substance. A consent screen nobody reads, with scopes nobody understands, granted permanently, is a legal artifact rather than genuine agreement.
DevRel is the function that owns the relationship between a company and the developers on its platform. You need the work — support, content, feedback, advocacy — long before you need a department.
Hypermedia means the API returns links telling the client what it can do next, rather than requiring out-of-band knowledge. Adoption among human developers stayed small — but AI agents may finally be the consumer it w...
The economic value created and exchanged through APIs. I opened API Evangelist on that idea in 2010 — the comparison being that where businesses in 2000 needed a website, businesses now need an API.
The full set of stages an API moves through — definition, design, development, deployment, management, documentation, testing, security, discovery, and eventually deprecation. It is the structure everything else in AP...
A public, versioned 0–100 rating of how ready an API is to be discovered, understood, adopted and operated — computed only from public, machine-checkable signals a provider chose to publish or chose to leave out.
The APIs you do not know you have, followed closely by broken object-level authorization on the ones you do. Both are inventory problems before they are code problems.
OpenAPI is the static source of truth describing what the API can do. A collection is an executable derivative describing how it is actually used, for a specific outcome. You want both.
REST thinks in resources and standard HTTP methods; RPC thinks in named actions with parameters. Neither is obsolete — RPC has come roaring back through gRPC.
OpenAPI is the specification; Swagger is the name of the original project and now a family of tools. Swagger 2.0 was donated and renamed OpenAPI in 2015 — if you are writing new specs, you want OpenAPI 3.x.
Historically a "web service" meant the SOAP and WS-* generation of enterprise interfaces; "web API" meant the simpler HTTP-and-JSON generation that displaced it. Today the terms are used loosely and mostly interchange...
Authentication verifies who you are. Authorization determines what you are allowed to do once you have been verified. Conflating them causes most API security confusion.
Capital-G Governance is the formal program — boards, mandates, gates, audits. Lowercase-g governance is the daily practice of teams making consistent decisions. The second is where governance actually happens.
Monitoring answers questions you already knew to ask. Observability is having enough signal — logs, metrics, traces, definitions, usage — to answer questions you had not thought of yet.
At minimum an OpenAPI document, the JSON Schema behind it, and interactive documentation generated from both. After that, a collection, an APIs.json index, and — when you have workflows — Arazzo.
Documented event types with schemas, signed payloads, delivery headers with an event ID, sane retries with backoff, a replay or delivery log, and a ping event so consumers can test.
The fewest possible steps between landing and a successful call. Self-service signup, an immediate key, a runnable example, and no application registration for people who only want their own data.
Availability and latency per operation, error rates by class, usage per consumer, and quota consumption — then alert on what breaks the consumer's experience, not just on what breaks your server.
The contract first — does the live API match its definition — then the unhappy paths. Most API test suites are heavily biased toward the happy path, which is where the fewest bugs live.
Interactive reference generated from your OpenAPI, a getting-started path to a first successful call, real working examples, error documentation, and a change log. Generated reference alone is not documentation.
Salesforce shipped what is generally considered the first commercial web API on February 7, 2000, followed by eBay in November 2000 and Amazon in July 2002 — though the underlying idea is decades older than that.
Only when you make a change that breaks existing consumers. Additive changes should ship without a version bump — and versioning is often a coping mechanism for a design or deadline problem upstream.
When you have graph-shaped data and consumers who need to assemble many related resources in one request — and who are willing to do the work of writing queries. It is a legitimate tool, not a replacement for REST.
When the consumer needs to know that something happened rather than to ask whether it has. If your consumers are polling you on a timer, you owe them an event.
For internal, high-performance, strongly-typed service-to-service communication where you control both ends. Not for a broad public API, where its browser and tooling story remains its weak point.
Mashery, Apigee and 3Scale — the original three, all founded in the mid-2000s — invented the category. The layer they built has since unbundled into gateways, portals, catalogs and governance.
With the landscape and the people, not the rules. Find out what APIs you actually have and who owns them, then write down a handful of things everyone already agrees on and automate those first.
Flickr proved a simple API on a beloved consumer platform could spawn an ecosystem. Twitter then became the most important API in this industry's history — and its most painful cautionary tale.
All of them, deliberately. Mature organizations run a diverse toolbox with HTTP at the pragmatic center and the others deployed where they genuinely earn their cost.
Open banking regimes (PSD2, the UK CMA order, Australia's CDR, the US §1033 rules) and healthcare interoperability rules (the Cures Act, CMS rules) are the clearest cases — regulation has become one of the strongest d...
The developer is the integration point; the customer is usually whoever signs the cheque. You have to serve both, and confusing them is one of the oldest business mistakes in this space.
Because publishing a dataset is not the same as sustaining a usable service. Most open data shipped without APIs, ownership, quality commitments, or a plan for who maintains it in year three.
Because they arrive as gates rather than guardrails, with rules nobody can trace to a reason, no feedback path, and no investment in the literacy that would let teams participate rather than comply.
Because integration is where business value actually shows up — and because building APIs forces an organization to find out what it actually has.
Usually because the ecosystem they invited in started competing with them, or because the data became more valuable sold than shared. The pattern is old and remarkably consistent.
Because an API is a power relationship encoded as a technical interface. It decides who can access what, on whose terms, with what recourse — and those have never been engineering questions.
Because nothing about an API is self-evident. The story is what connects a technical capability to something a specific person cares about — and without it, good APIs go unused.
Because both took a genuinely painful, regulated domain and made it feel simple — and that is enormously hard, expensive, and slow. Most API startups skip the hard part and ship a thin wrapper.
Because it is not primarily a technical problem. The formats exist and work; the incentives do not — the effort falls on providers while the benefit accrues to the ecosystem.
Because it solves a genuinely hard problem — delegated access without sharing passwords — and because most implementations bolt an application registration and a multi-leg dance onto what the user experiences as "let ...
Because almost every "new" idea in this space is a returning one, and knowing the previous round tells you which problems are genuinely solved and which are about to be rediscovered at expense.
No. Agents are API consumers — the most demanding ones yet. What changes is that the quality of your contract, schema and documentation now determines whether a machine can use you at all.
