You keep hearing the term and want to know what is an API. In short, it’s a set of rules that lets one program ask another for data or an action and get a predictable reply.
This guide sits within the wider topic of technology in business, which looks at how everyday tools shape the way companies work.
| Item | Value |
|---|---|
| Year REST was first defined | 2000 |
| REST design principles (architectural constraints) | 6 |
| Fundamental HTTP methods (verbs) | 4 |
| Principal parts of a client request | 4 (method, endpoint, header, body) |
| Server-side sessions a REST API requires | None |
These figures come from IBM’s REST API explainer and TechTarget’s REST API definition. Documentation changes over time, so check the sources before you rely on them.
How does an API work?
Red Hat describes an API as “a set of definitions and protocols for building and integrating application software” (Red Hat). It adds that an API is sometimes called a contract between an information provider and an information user.
Red Hat’s own example is a weather service. The API design could specify that the user supplies a zip code and that the producer replies with the high and low temperature. Both sides know what to send and what to expect back.
You can think of an API as a mediator between the people or programs asking and the service holding the information. It also lets an organization share resources while maintaining security, control and authentication, according to the same Red Hat page.
What does an API request contain?
Most web APIs follow a simple pattern: a client asks, and a server answers. TechTarget says client requests include four principal parts:
- HTTP method: what should happen to the resource.
- Endpoint: where the resource is located, usually a web address.
- Header: details needed to run the call, such as authentication data.
- Body: any data sent to or from the server.
The method is the part that states your intent. In the same TechTarget definition, POST creates a new resource, GET retrieves an existing one, PUT updates it and DELETE removes it. Those four are the fundamental HTTP methods, often called verbs.
The server then replies with a status code that says how things went. Google Cloud’s guide gives examples: 200 OK for success, 404 Not Found if the resource doesn’t exist, and 401 Unauthorized for security issues. The reply also carries the requested data, most often as JSON, which Google Cloud calls the most common format because it is lightweight, human-readable and easy for programming languages to parse.
What makes an API “RESTful”?
You will often see the phrase REST API. REST is a style, not a product: Red Hat stresses that it is “a set of architectural constraints, not a protocol or a standard” (Red Hat). IBM notes that it was first defined in 2000 by computer scientist Roy Fielding in his doctoral dissertation.
IBM lists six design principles that an API must follow to be called RESTful (IBM):
- Uniform interface: requests for the same resource look the same, wherever they come from.
- Client/server decoupling: the two sides must be independent of each other.
- Statelessness: each request carries all the information needed to process it.
- Cacheability: resources should be cacheable on the client or server side where possible.
- Layered system: neither side should assume it talks directly to the other.
- Code on demand: optional, and rarely needed.
Statelessness has a practical effect. IBM says REST APIs do not require any server-side sessions, so the server does not have to remember you between calls.
REST is not the only approach. IBM points out that some APIs, such as SOAP or XML-RPC, impose a strict framework on developers, whereas REST APIs can be built in virtually any programming language.
Why do businesses rely on APIs?
APIs let separate systems cooperate without being rebuilt around each other. Google Cloud says the client-server split allows developers to work on the front end and the back end independently, which can accelerate development cycles. It also says a REST API can be implemented in any programming language and consumed by any client that can make HTTP requests (Google Cloud).
TechTarget lists everyday uses (TechTarget):
- Mobility: mobile apps such as Lyft and Uber use REST APIs to access maps and schedule rides.
- Weather: weather apps pull conditions, forecasts and historical data.
- Banking and e-commerce: these apps use REST APIs to access account data and support transactions.
For a small business, the same idea shows up when your accounting tool pulls figures from a payment service. If you are weighing how connected tools fit into bigger change, the guide on what is digital transformation covers the broader picture.
How are APIs kept secure?
An API opens a door into a system, so access control matters. IBM recommends hashing algorithms for password security and HTTPS for secure data transmission. It adds that an authorization framework like OAuth 2.0 can help limit the privileges of third-party applications (IBM).
IBM also notes that, using a timestamp in the HTTP header, an API can reject any request that arrives after a certain time period. Google Cloud’s advice is to always use TLS/SSL to encrypt traffic (Google Cloud).
These are design practices for the people building an API. If you run a small company and use services that rely on them, the guide to cybersecurity for small business covers the everyday protections on your side.
Frequently asked questions
Is an API the same as a website?
Show answer
No, but they work alike. IBM says a well-designed REST API is similar to a website running in a web browser with built-in HTTP functionality, though an API returns data for programs rather than pages for people (IBM).
What is an API key?
Show answer
It is a piece of authentication data. freeCodeCamp explains that a request’s HTTP headers include authentication data such as an API key, which identifies who is asking (freeCodeCamp).
Does an API only return JSON?
Show answer
No. IBM says the data can be delivered in virtually any format, including JSON, HTML, XLT, Python, PHP or plain text. JSON is simply the popular choice because both humans and machines can read it (IBM).
What does a 404 error mean?
Show answer
It means the server could not find the resource you asked for. Google Cloud gives 404 Not Found as the example of a response when the resource doesn’t exist (Google Cloud).
