An API is one of the ways software asks other software for information or action. This guide follows a simple request from an application to a service and back, explaining the vocabulary you will encounter without requiring you to write a working integration.
How Do APIs Let Systems Communicate?
An application programming interface, or API, defines rules that software can use to interact with another component or system. For a typical web API, a client sends a request to a server, and the server returns a response containing data or a result. The API exposes agreed capabilities without requiring the client to understand every internal detail of the service.
An interface is a contract, not necessarily a separate program
Think of an API as an agreed way to ask for something. A weather application might ask a weather service for a forecast at a location. The weather service decides how to retrieve or calculate that information, while the app decides how to display it.
The interface defines the available requests, their required information, and the possible responses. It does not necessarily translate arbitrary software languages, and it does not guarantee that systems with different data models automatically understand one another.
APIs are broader than internet services. An operating system can expose APIs for opening files, and a programming library can expose functions that other code calls inside the same application. This guide focuses on web APIs because they are common when connecting independent services.
MDN's HTTP overview describes the client-server request-response model used by the web. Many web APIs use that same foundation, although not every API uses HTTP and not every HTTP API follows the same design style.
The client is the software initiating a particular request; the server is the software responding. Those are roles, not permanent labels for devices. A website's backend can be a server to a visitor's browser and a client when it requests data from a separate payment service.
Follow one request from start to finish
Suppose a travel application displays a local weather forecast. When you select a destination, the app may send a request containing a location identifier and the period you want. The service receives the request, checks whether it is valid and allowed, obtains the forecast, and returns a structured response.
Several distinct activities happen along the way. The client builds a URL and chooses an HTTP method. It may attach credentials or other headers. The server interprets the request according to its contract, then produces a status code, response headers, and often a response body.
The app still has work to do after the response arrives. It must interpret the data, choose units and labels, and handle missing or unavailable information. An API response is not automatically a finished screen.
This exchange can be fast, but it is not guaranteed to complete in milliseconds. Network conditions, server load, large datasets, and background processing affect timing. Some APIs return a task identifier and ask the client to check back later rather than keeping one request open until completion.
A web page can also make several API requests for one visible action. Loading an order screen might retrieve account information, shipment status, and product details separately. One part can succeed while another fails, which explains why applications sometimes show partial information.
Understand endpoints, methods, headers, and bodies
An endpoint is an address where an API exposes a capability or resource. In many HTTP APIs, the method and URL together identify the intended operation. Query parameters add information to the URL, while a request body can carry a larger structured payload.
| Term | Plain meaning | Illustrative example |
|---|---|---|
| Endpoint | Address for an API operation or resource | /forecast |
| Method | Type of requested HTTP action | GET to retrieve information |
| Query parameter | Extra value included in the URL | city=example-city |
| Header | Metadata attached to a message | Desired response format |
| Request body | Content sent with a request | Details for a new booking |
| Status code | Standard signal about the response | 404 for a resource not found |
| Response body | Returned data or error details | Forecast fields in JSON |
GET commonly retrieves a representation of information. POST commonly submits data for processing or creates a resource. PUT, PATCH, and DELETE have other standard meanings, but an individual API's documentation tells you exactly what its endpoints support.
Do not infer safety from an endpoint's name. A request that creates a booking or sends an email has consequences, even if the code needed to call it is short. Conversely, knowing an endpoint's address does not imply that you are authorized to use it.
Some APIs place version information in a URL or header. Versioning helps services evolve without forcing every client to change at the same moment, but providers still have their own support and retirement policies.
A worked example of a JSON response
JSON, short for JavaScript Object Notation, is a common format for structured data. It represents values such as strings, numbers, booleans, lists, and objects. Despite its name, software written in many programming languages can read it.
Here is a hypothetical response from a fictional weather API. The location and numbers are illustrative, not actual observations:
{
"location": "Example City",
"temperature_c": 18,
"rain_expected": false,
"forecast_hours": [9, 12, 15]
}
The app could display “18°C” using temperature_c. It could choose a dry-weather icon because rain_expected is false. The list in forecast_hours could help populate available forecast times, if the API documentation defines those values that way.
Notice what the example does not establish. It does not identify the time zone, observation time, forecast confidence, or meaning of a missing field. The field names help, but the contract supplies the full meaning.
A string containing “18” is also different from the number 18. That distinction can matter when software compares, sorts, or calculates values. Clients need to handle the documented types rather than guessing from what looks readable to a person.
JSON is not the only possible response format. APIs can return XML, text, binary files, or streaming data. A format specifies how information is represented; it does not determine whether that information is accurate or whether you have permission to use it.
Authentication and authorization answer different questions
Authentication concerns the identity or credential presented by the caller. Authorization concerns what that caller may do. A valid credential does not automatically grant access to every customer record or administrative operation.
An API key often identifies a calling application or project and may carry access privileges. A token may represent an application, a person, or a delegated grant, depending on the system. OAuth is commonly used for delegated authorization, but the details depend on the service and its implementation.
Imagine a calendar app asking to read events from another service. A permission screen might let you grant read access without granting the ability to delete events. The app should receive only the access needed for its purpose, and you should have a way to revoke it.
Credentials need protection. A secret included in browser-delivered code can generally be inspected by the person running that browser. Some APIs intentionally support public client identifiers, but that is different from safely hiding a secret inside a web page.
HTTPS helps protect information while it travels between the client and server. It does not establish that every recipient is trustworthy or that every requested action is appropriate. Security also depends on access rules and how each system stores and uses the information afterward.
Why API calls fail and what the limits mean
A request can fail because its input is invalid, credentials are missing, access is denied, a resource does not exist, or a service is temporarily unavailable. MDN's status-code reference explains the standard HTTP categories used to communicate these outcomes.
A status code is a useful starting signal, not the entire explanation. The response body may describe a missing field or an expired permission. Some APIs also report item-level outcomes inside a larger successful response, so applications must read the relevant contract.
Rate limits restrict how much work a caller may request within a defined period or quota. They help control service load and sometimes reflect commercial plan limits. They are not the same thing as response speed, and a higher quota does not guarantee lower latency.
A network timeout introduces uncertainty: the client did not receive a timely answer, but the server may already have acted. This is especially important for payments and orders. Reliable integrations need deliberate retry behavior rather than assuming that silence always means failure.
APIs may charge by request, stored data, active users, processing, or another measure. A development tier can be free while production use is paid, but neither arrangement is universal. Read the actual terms, data rights, and plan limitations before depending on a service.
Questions About How APIs Work
Is an API the same as a database?
No. A database stores and organizes information. An API defines an interface for requesting information or actions and may use one or more databases behind the scenes. It can expose selected capabilities without allowing direct database access.
What does REST mean?
REST means Representational State Transfer, an architectural style with constraints for networked systems. Many APIs described as REST use HTTP methods and resource-oriented URLs, but using JSON over HTTP alone does not establish every REST property.
Are webhooks the same as ordinary API requests?
A webhook is an event-triggered request sent to a registered receiver. Rather than your application repeatedly asking whether an event occurred, the other service sends a notification. The receiver still needs to verify and interpret the request.
Can nonprogrammers use APIs?
Yes. Automation tools and application connectors can construct requests behind a visual interface. Users still need to understand permissions, data meaning, errors, and potential side effects, even when they do not write the underlying code.
Think of APIs as Defined Interfaces
An API is a defined interface that lets software collaborate without exposing every internal implementation detail. Understanding the request, response, permissions, and data contract makes it easier to reason about both the possibilities and the limits.
Next steps: Turn the concept into a plan with API planning guidance, compare services using the API evaluation guide, and use the integration checklist when implementation begins.
Sources
- MDN — Overview of HTTP
- MDN — HTTP response status codes
This guide is general education, not professional advice.