Most software projects now include an API, whether or not anyone asked for one by name. Your mobile app needs it to talk to your servers. Your accounting system needs it to receive orders. A partner wants to pull your stock levels. An AI assistant needs it to look up a customer record. If the API is designed badly, every one of those connections becomes slower and more expensive to build, and some become security problems.
This guide explains API development for business readers: how REST, GraphQL, webhooks and gRPC differ, what "API-first" means, and what to check before you sign off on a build.
Quick answer
- An API (application programming interface) is a defined way for one piece of software to request data or actions from another.
- REST is the default choice for most business APIs: predictable URLs, standard web behavior, widely understood.
- GraphQL suits products with many different screens or clients that each need different slices of the same data.
- Webhooks are not an alternative to REST or GraphQL. They are how your system tells another system that something happened, without being asked.
- gRPC is mainly for fast communication between your own internal services.
- API-first means the API is designed and agreed as a contract before the screens are built, so the website, the mobile apps, partners and AI agents all use the same foundation.
Most real products combine these: a REST or GraphQL API for requests, plus webhooks for notifications.
What an API is, and why it matters commercially
Think of an API as a service counter with a published menu. The menu lists what you can ask for, what you must provide, and what you will get back. The systems behind the counter can change without breaking everyone who depends on it. An API pays for itself in four places:
- Integrations. Connecting your product to a CRM, payment provider, accounting package or warehouse system is an API job. Without a clean API of your own, each integration becomes a one-off project.
- Mobile apps. An iOS or Android app is a client of your API. The same API should serve the web app too, so business rules live in one place. Our comparison of native, Flutter and React Native covers the app side of that decision.
- Partners and customers. Larger customers often ask whether they can connect your product to their own systems. A documented API can be the difference between winning and losing that deal.
- AI agents. An AI model cannot act on your business by itself. It needs tools, and tools are usually API calls. Anthropic's documentation describes tool use as letting a model call functions that you define, each with a name, a description and an input schema. The Model Context Protocol (MCP) is an open standard for connecting AI applications to external systems in a consistent way. See AI agents vs chatbots vs workflow automation.
REST vs GraphQL vs webhooks vs gRPC
These four are tools for different jobs, not rivals.
| Style | How it works | Use it when | Think twice when |
|---|---|---|---|
| REST | Each resource (a customer, an order) has its own URL. Clients use standard web methods to read, create, update and delete. | You are building a public or partner API, a typical web or mobile back end, or anything third parties must integrate with quickly. | Screens need data from many resources at once and the number of round trips is hurting performance. |
| GraphQL | One endpoint. The client sends a query describing exactly which fields it wants and gets that shape back. | You have several clients (web, iOS, Android, partner portals) with different data needs, and a front-end team that changes screens often. | The API is simple, the team has no GraphQL experience, or you rely heavily on standard web caching. |
| Webhooks | Your system sends a message to a URL the other party registered when an event occurs, such as "invoice paid". | Another system needs to react to events promptly, and constant checking ("polling") would be wasteful. | The receiver needs guaranteed order or exactly-once delivery. Webhooks need retries and duplicate handling to be dependable. |
| gRPC | One program calls a function on another machine as if it were local, using a compact binary format over HTTP/2. | Your own services talk to each other at high volume, or you need streaming between systems you control. | The consumers are outside developers or browsers, where plain web conventions are easier to adopt. |
REST
REST is an architectural style described by Roy Fielding in his 2000 doctoral dissertation, built around constraints such as statelessness, cacheability and a uniform interface. In practice, "REST API" usually means a web API with sensible URLs and JSON responses. Its advantage is familiarity. Its weakness is that a complex screen may need several requests, or receive more data than it needs.
GraphQL
GraphQL addresses that weakness. A GraphQL service operates on a single endpoint, and clients request exactly the data they need against a strongly typed schema. That flexibility moves work to the server side: because clients can compose their own queries, the team must guard against expensive or abusive ones, and authorization has to be enforced field by field.
Webhooks
Webhooks reverse the direction of the call: your system notifies the other party when something changes. Practice varies between providers. Stripe's documentation is a useful reference for what good looks like: it tells receivers to verify a signature on every event, expect occasional duplicates, not rely on the order of delivery, and acknowledge quickly before doing heavy processing. If your product will send webhooks, it should sign them, retry failed deliveries and give customers a log of what was sent.
gRPC
With gRPC, a client application can call a method on a server on a different machine as if it were a local object, with the contract defined in Protocol Buffers. It runs over HTTP/2 and supports streaming in both directions. Browser support exists through the separate gRPC-Web project, but for an API that outside developers will use, REST remains the easier offer.
What "API-first" means
In a screen-first project, the team builds the pages and adds whatever back-end endpoints each page happens to need. The API is a by-product, shaped by one front end and usually undocumented.
In an API-first product, the team agrees the contract (resources, fields, errors, permissions) before building screens, writes it down in a machine-readable format, and treats every client, including its own website, as a consumer of that contract. The practical consequences:
- Web and mobile teams can work in parallel against the agreed contract.
- Adding a partner integration or an AI agent later does not require reworking the back end.
- Business rules are enforced in one place, not duplicated in each app.
- It costs more design time up front, and that cost is wasted on a small brochure website or a short-lived prototype.
Illustrative scenario (not a client case study): a field-service company commissions a booking web app, then a year later wants a technician mobile app, an accounting feed and an AI assistant that can reschedule visits. Built screen-first, each addition needs back-end rework, because the original endpoints return page-shaped data and assume a logged-in browser. Built API-first, they are mostly new clients of an existing contract.
Authentication: API keys and OAuth 2.0
Authentication answers "who is calling?" Authorization answers "what are they allowed to do?" APIs need both, and the OWASP list further down shows how often the second is where things go wrong.
| Method | What it is | Appropriate for | Limits |
|---|---|---|---|
| API key | A long secret string issued to a calling system and sent with every request. A convention, not a single formal standard. | Server-to-server integrations where the caller is one organization. | Identifies an application, not a person. Anyone holding the key can use it, so keys need scoping, rotation and revocation. |
| OAuth 2.0 | A framework that lets an application obtain limited access on a user's behalf, or on its own behalf, without handling the user's password. | "Connect your account" features, third-party apps, mobile and single-page apps, delegated access for AI agents. | More moving parts. Easy to implement incorrectly without an established library or identity provider. |
OAuth 2.0 is defined in RFC 6749, which describes it as enabling a third-party application to obtain limited access to an HTTP service. The access tokens it issues are usually bearer tokens, and RFC 6750 is blunt about what that means: any party in possession of the token can use it, so tokens must be protected in storage and in transit, and TLS (HTTPS) is mandatory.
The questions that matter commercially are whether tokens expire, whether access can be limited to specific permissions, and whether one customer's access can be revoked without affecting others.
Versioning: changing the API without breaking customers
Once other systems depend on your API, you cannot freely rename a field or remove an endpoint. A change that breaks a partner's integration breaks their business process.
Common approaches are a version in the URL (such as /v1/) or in a request header. GraphQL encourages evolving the schema over time without versions, adding new fields and retiring old ones gradually.
The mechanism matters less than the policy. Ask what counts as a breaking change, how much notice consumers get, and how long old versions stay alive. There are now standard ways to signal retirement in the API responses themselves: the Deprecation header (RFC 9745) and the Sunset header (RFC 8594).
Rate limiting
Rate limiting caps how many requests a caller can make in a period. It protects you from a buggy integration that loops, from deliberate abuse, and from one heavy customer degrading the service for everyone else.
The standard response when a caller exceeds the limit is HTTP status 429 Too Many Requests, which may include a Retry-After header telling the caller how long to wait. Limits should be documented, applied per customer or key, and stricter on expensive operations such as exports or anything that triggers paid third-party calls.
Documentation and OpenAPI
An API nobody can understand has no commercial value. The OpenAPI Specification defines a standard, language-agnostic description of HTTP APIs that both humans and computers can read. The current published version at the time of writing is 3.2.1.
An OpenAPI file is a deliverable worth asking for. Teams commonly use it to produce interactive documentation, client libraries, tests and mock servers. It is also a practical starting point for exposing your API to AI agents, because tool definitions need the same information: operation names, descriptions and input schemas. Documentation that is generated from, or tested against, the real code stays accurate.
Security: the OWASP API Security Top 10
The OWASP API Security Project publishes a widely referenced list of API risks. The current edition is 2023, which replaced the 2019 list. In plain terms:
- Broken Object Level Authorization. A user changes an ID in a request and sees someone else's record.
- Broken Authentication. Weak login or token handling lets an attacker act as another user.
- Broken Object Property Level Authorization. The API reveals, or lets a user change, fields they should not have access to.
- Unrestricted Resource Consumption. No limits on request volume or size, leading to outages or large bills.
- Broken Function Level Authorization. Ordinary users can reach administrative functions.
- Unrestricted Access to Sensitive Business Flows. A legitimate feature is abused at scale by automation.
- Server Side Request Forgery. The API fetches a URL supplied by the user without validating it.
- Security Misconfiguration. Insecure defaults, missing hardening or overly detailed error messages.
- Improper Inventory Management. Old versions and forgotten endpoints remain exposed.
- Unsafe Consumption of APIs. Data from third-party APIs is trusted more than it should be.
Three of the ten are authorization failures. For the first, OWASP's guidance is to check that the logged-in user has access to the requested record in every function, and to write tests for it. This matters even more once AI agents call your API, since an agent will follow instructions and try whatever its permissions allow.
US and UK note. If your API exposes personal data, security is also a legal matter. In the UK, the Information Commissioner's Office explains that UK GDPR requires appropriate technical or organizational measures to protect personal data. In the US there is no single equivalent law; obligations come from sector rules and state laws, and the Federal Trade Commission publishes data security guidance for businesses. This is a high-level summary, not legal advice. Take advice on your own situation.
For technical readers
- OAuth flows. The IETF's Best Current Practice for OAuth 2.0 Security (RFC 9700) says the resource owner password credentials grant must not be used, that clients should not use the implicit grant, and that public clients must use PKCE. OAuth 2.1 consolidates these practices but is still an Internet-Draft, not a published RFC, at the time of writing.
- Rate limit headers. Standardized RateLimit and RateLimit-Policy header fields are also still an IETF draft. Document whichever headers you return.
- Idempotency. Accept an idempotency key on create and payment operations so a retried request does not create a duplicate, and give each webhook event a stable ID so receivers can discard repeats.
Questions to ask a development company about your API
- Which API style are you proposing, and why does it fit our clients and partners better than the alternatives?
- Will the API contract be designed and reviewed before the screens are built?
- Will we receive an OpenAPI document or GraphQL schema, and how is it kept in step with the code?
- How will callers authenticate, and how are permissions scoped, rotated and revoked?
- How do you make sure one customer cannot read another customer's data, and how is that tested?
- What is the versioning and deprecation policy, and how much notice will consumers get?
- What rate limits apply, and what happens when a caller exceeds them?
- Will the product send webhooks? Are they signed and retried, and can customers see a delivery log?
- How is the API checked against the OWASP API Security Top 10 before launch?
- What logging and monitoring will exist so we can see who called what, and when?
Vague answers to questions 5, 6 and 9 are the ones to worry about. If you are hiring an overseas team, our guide to outsourcing software development from the US and UK covers contracts, ownership and vetting in more depth.
Frequently asked questions
How much does it cost to build an API?
There is no honest standard price. The effort depends on how many operations the API exposes, how complex the permission model is, how many third-party systems it must connect to, whether it is private or open to outside developers, and how much security testing, monitoring and documentation is in scope.
Are webhooks an alternative to an API?
No. Webhooks complement an API. The API lets other systems ask you for data or actions. Webhooks let you tell other systems that something happened. Most products that integrate well offer both.
Can AI agents use our existing API?
Often, yes, if the API is documented, uses clear names and returns useful error messages. An agent needs each operation described as a tool with defined inputs. You should also give the agent its own narrowly scoped credentials, apply rate limits, and require human approval for actions that are costly or hard to reverse.
How do we know if our API is secure?
Ask for evidence, not reassurance: automated tests for authorization on every endpoint, a review against the OWASP API Security Top 10 (2023), an inventory of every exposed endpoint and version, and independent penetration testing for anything handling personal or financial data.
Conclusion
An API is a long-lived commitment to every system that connects to yours. The choice of style matters less than the disciplines around it: a documented contract, sound authentication and authorization, a versioning policy, rate limits and testing against known risks.
A useful next step is to list every system, app, partner and automation that will need to talk to your product over the next two to three years, then take the questions above to whoever is building it. Entrant Technologies builds websites, web applications, mobile apps and custom software; if you would like a second opinion on an API plan, you can send us your requirements.
