An API, or application programming interface, is a defined way for software to use another software component’s features or data. Web APIs often exchange HTTP requests and structured responses. APIs also exist inside operating systems and libraries. They make integration easier, but callers must follow the service contract, permissions, limits and security requirements.
APIs are behind everyday digital services, from maps and weather widgets to store inventory and parcel tracking. This guide explains them through practical examples, sample messages and the decisions that make an integration reliable.
What Is An API In Plain English
API stands for application programming interface. An interface is an agreed boundary through which one piece of software can use another piece of software’s capabilities. It defines the operations that are available, the information a caller must provide, the format of results and the behavior that callers can reasonably expect. An API may connect two programs running on the same computer, or it may connect applications hosted in different parts of the world.
Think of a restaurant menu. A customer can order a meal described on the menu without entering the kitchen or knowing the design of its ovens. The menu and ordering process establish an agreement about what can be requested. Staff fulfill that request and return the result. Software interfaces provide a similar separation between the caller and the implementation. Unlike a restaurant waiter, however, a programming interface is a specified set of rules rather than necessarily a separate person or service.
Suppose a calendar application needs to remind you about an appointment. It can use operating-system notification APIs to request that the device display a notification. The application does not need to program the screen electronics directly. The operating system manages permissions, notification placement and the supported presentation. A separate web API could let the calendar synchronize appointments with a remote account. Both are APIs, even though only one involves a network.
This separation helps developers improve the implementation while preserving compatible behavior for callers. It also creates obligations: changing a required parameter, data type or permission unexpectedly can break dependent applications. The MDN API glossary provides an introduction to the concept. Our technology glossary explains related vocabulary.
APIs, Applications, Websites, And Databases
An application is software that performs tasks for a user or another system. A website generally presents information and interactive features through a browser. A database organizes and stores records. An API describes how a caller can use selected capabilities. These categories overlap in practice but are not interchangeable. A web application may expose an API that reads from several databases and calls other services, then returns a deliberately limited result.
Consider a library’s online catalog. The public website might display title, author and availability. A catalog API may return those fields in a form that another application can process. The database behind it could contain account details, internal purchase records and circulation history. Public catalog access should not automatically reveal those private records. Proper authorization at the service boundary determines which information is available.
A web API is not necessarily a public endpoint. Private services inside a company may communicate through APIs that are unavailable to ordinary internet users. Conversely, a browser itself offers APIs such as the DOM, which allows scripts to work with page elements. A software library that calculates dates may offer functions without requiring a remote server at all.
The distinction matters when troubleshooting. If a page loads but its list of products is empty, the display code might be functioning while a data service fails. If the database is healthy but the caller lacks permission, refreshing the page repeatedly will not grant access. You need to locate the failing boundary rather than assuming every problem is a database fault.
How An API Request And Response Work
Many web APIs communicate using HTTP. A client, such as a mobile application or backend service, sends a request to an address associated with a service operation. The server interprets the request, verifies applicable credentials and permissions, reads or changes data as appropriate, and returns a response. Network protocols carry the messages between these endpoints. Our router guide and DNS guide explain the underlying connectivity and naming concepts.
A sample library API offers an endpoint named /books/42. An application requests information about book 42. The service checks that the record exists, determines what information the application is permitted to receive and returns a structured representation. The application might display a title and lending status rather than raw data. Use a service’s documented endpoint when integrating a live API.
The request typically contains a method, a target URI and headers that carry details such as acceptable response formats or authentication information. Depending on the operation and API contract, a request can also carry content in its body. Responses normally include a status code, headers and an optional body. A successful operation may deliberately return no body at all.
The server need not complete every action immediately. An operation such as creating a large report may acknowledge a request and provide a job identifier. The client can later check whether the report is ready. Likewise, a request that reaches the server may be processed successfully even if the connection breaks before the client receives the response. That distinction becomes especially important for payment, ordering or other operations with real consequences.
HTTP Methods And Resource Operations
A method communicates the intended semantics of an HTTP request. GET commonly retrieves a representation without requesting a change to the resource. POST commonly submits data for processing, which may create a resource or trigger another action. PUT generally requests creation or replacement of the state at the target URI, and PATCH applies a partial modification according to the supported patch format. DELETE requests removal of the association between the target URI and its current functionality. The API’s documentation determines exactly which operations it offers.
A product catalog might use GET /products to list entries and GET /products/42 to retrieve one item. An authorized administrator might use POST /products to create a product. An application must not assume these paths exist merely because another provider uses similar names. Naming conventions help people understand interfaces, but they are not a universal contract.
HTTP distinguishes safe methods, which are meant for retrieval rather than requested changes, from methods that can change state. It also defines idempotent methods, for which repeating the same intended operation has the same intended effect as doing it once. For example, a correctly implemented PUT that replaces a record with the same values can be repeated without creating additional records. A POST that creates an order may have a different effect on each request. A server can still log each request separately.
Read MDN’s HTTP methods reference for the formal semantics. An API designer should choose methods consistently, document side effects and restrict operations to authorized callers. A client should follow those documented rules instead of treating every method as an interchangeable way to send data.
How JSON Structures API Responses
JSON, or JavaScript Object Notation, is a text-based data format used by many web APIs. It can represent objects with named fields, arrays of values, strings, numbers, booleans and null. Despite its name, it is not limited to applications written in JavaScript. Most popular programming languages provide libraries for reading and writing JSON.
Imagine a weather application receiving the sample object below. The location, temperature, unit and observation time are separate fields. The application can display the temperature in large text, use the condition to select an image and print the time as a smaller caption. The values are sample data for learning the response format. The meaningful point is the agreement between the service’s response structure and the application’s interpretation.
Units and timestamps are especially important. A temperature value without a unit is ambiguous. A timestamp without a stated time zone can create confusion around local dates. A good interface provides fields or documentation that establish these meanings. When financial amounts are involved, the client should also follow the provider’s specified currency and numerical representation rather than making assumptions about decimal precision.
Not every API returns JSON. A service might return XML, a binary file, an image, or another documented representation. Clients should inspect the supported media type and handle missing or unexpected data safely. If a field is optional, an application must be prepared for its absence. If parsing fails, showing a helpful error is usually preferable to silently displaying an incorrect number.
{
"location": "Greenfield",
"temperature": 21,
"unit": "C",
"condition": "Cloudy",
"observed_at": "2026-11-14T10:00:00Z"
}HTTP Status Codes And What They Tell You
The status code describes the result of an HTTP exchange at the protocol level. Successful responses generally use codes in the 200 range. Redirects use the 300 range, client-side request problems commonly use codes in the 400 range, and server-side failures commonly use codes in the 500 range. The detailed response body can provide application-specific information that the status code does not express.
A 200 response generally indicates successful handling, but it does not prove that every business expectation was met. A response can contain an empty result because the query matches no records. A 201 response indicates that resource creation occurred; a 202 response can indicate accepted processing that is not finished. A 204 response is successful without response content.
A 401 response means the request lacks valid authentication credentials for the target resource. A 403 response means the server refuses to fulfill the request; changing a password may not solve a permission problem. A 404 response indicates that the target was not found or that the server is unwilling to disclose its existence. A 429 response reflects excessive requests under an applicable limit. A 503 response may indicate temporary service unavailability. Read the provider’s response details and MDN’s status reference.
Do not blindly retry every unsuccessful request. A malformed input may need correction, a missing permission may require an authorized approval, and a temporary failure may call for a delayed retry. An operation involving money or record creation needs particular care if the outcome is unknown. A status code is the beginning of diagnosis, not a universal repair instruction.
| Status | Meaning | Useful Next Check |
|---|---|---|
| 200 | Successful response | Validate the result |
| 401 | Valid credentials required | Check supported authentication |
| 403 | Request refused | Verify authorized permissions |
| 404 | Resource not found or not disclosed | Check documented endpoint and identifier |
| 429 | Too many requests | Respect provider retry guidance |
| 503 | Service unavailable | Check status and allowed retry policy |
Everyday Examples Of APIs
Weather widgets often request a forecast or observation from a weather service. The application chooses how to present that information, while the provider maintains the underlying data system. Freshness, permitted usage and forecast meaning are all part of the integration. If the provider stops returning data, the widget may need to show the last known update with a clear timestamp rather than pretending it is current.
Mapping applications request map tiles, routes, search results or location-related information through documented services. A delivery application may combine address entry, route calculation and driver updates from different systems. It must respect each provider’s licensing rules and handle personal location data carefully. A map route is not guaranteed to represent actual road conditions at the time of travel.
Online payments offer another useful example. A store can delegate parts of payment processing to a specialized provider. The exact responsibilities for card handling and compliance depend on how the integration is designed. An application should not assume that using any payment API automatically removes all security or regulatory obligations. Use the provider’s supported integration and distinguish an initiated payment from a confirmed result.
Courier tracking, booking systems and calendar synchronization use similar request-and-response patterns. A parcel tracking application can show the latest reported event without claiming the parcel itself is continuously transmitting its position. The provider’s data may arrive late or contain only the most recent scan. The interface transports information; the meaning and limitations of that information still matter.
REST, GraphQL, SOAP, And Webhooks
REST is an architectural style for distributed systems rather than a file format. RESTful services are often organized around resources and HTTP semantics. Many APIs described as REST APIs follow some resource-oriented conventions without implementing every architectural constraint. A beginner can understand the practical style without assuming all JSON-over-HTTP interfaces are identical.
GraphQL describes a typed service schema and a query language through which a client can select available fields. Instead of retrieving a fixed representation from several resource addresses, a client may request a selected combination of related fields. That does not guarantee every operation is cheaper or faster. Service implementation, resolver behavior, access checks and query complexity affect performance. The official GraphQL learning resources explain schemas, queries and mutations.
SOAP is a messaging protocol associated with structured XML messages and formal service contracts. It remains relevant in some enterprise and legacy integrations. Whether it is appropriate depends on the existing platform and requirements. Its use is not by itself proof that a service is outdated or unreliable.
A webhook is a different communication pattern: a service sends an event notification to a configured receiving endpoint when something happens. Rather than continually asking whether a shipment or payment has changed, an application can receive a notification and then take the documented action. Webhooks are often used alongside resource APIs. They are not a replacement for verifying the sender, handling repeated deliveries or reconciling important state.
| Approach | Typical Use | Check First |
|---|---|---|
| REST-style HTTP | Resource operations | Methods and representations |
| GraphQL | Selected related fields | Schema and query limits |
| SOAP | Structured service messaging | Contract and supported operations |
| Webhook | Event delivery | Sender verification and duplicate handling |
Public, Partner, And Internal APIs
Public APIs are intended for use by external developers under defined terms. Public does not necessarily mean that authentication is unnecessary, that all data is free or that every caller receives identical access. A provider may require registration, restrict particular features to a paid tier or apply regional conditions. A documented public interface is quite different from an undocumented endpoint discovered accidentally.
Partner APIs support specific business relationships. A merchant and logistics provider may share access to order and shipment operations protected by contractual and technical controls. The integration may require approved network locations, credentials or additional identity checks. Callers should only use the permissions granted for their actual relationship.
Internal APIs enable teams to connect components within an organization. A company could maintain separate services for inventory, customer accounts and order fulfillment. Each offers a controlled interface rather than allowing every team to edit the underlying data directly. Internal placement does not eliminate the need for authentication, authorization and monitoring. A compromised internal account or service can still cause damage.
When selecting an API, confirm the access model before developing the entire application. A sandbox, a public test environment and a production environment may behave differently or expose different datasets. Obtain permission for the intended use and do not test unknown credentials or private endpoints simply because they respond to network requests.
API Keys, Tokens, Authentication, And Authorization
Authentication establishes relevant identity or credential validity. Authorization determines whether that identity may perform a particular action. These are separate responsibilities. A valid token for a library account, for example, should not permit the caller to change another person’s borrowing history or administer the catalog without the appropriate permission.
An API key may identify an application or associate requests with a project and usage quota. Some keys are specifically designed for public client use under restrictions; other keys are secret credentials. Read the provider’s security model rather than placing a secret key in browser JavaScript, screenshots, public repositories or mobile application bundles where it may be extracted. Privileged service credentials generally belong in a protected backend or managed secret store.
Access tokens may carry or reference granted permissions and expiration information. OAuth is an authorization framework frequently used when an application needs delegated access to a service. OpenID Connect builds an identity layer on OAuth 2.0 for sign-in use cases. The presence of an OAuth login button is not itself proof that the application is trustworthy; review the consent request and the service identity.
For personal accounts, the two-factor authentication guide explains stronger sign-in methods. The password manager guide discusses everyday credential storage. Application secrets, however, often require dedicated infrastructure for restricted access, rotation and audit logs. If a privileged key leaks, revoke or rotate it through the real provider and investigate possible usage.
Security Risks And Defensive API Design
A service should validate what a caller sends and only return information appropriate to the caller’s permissions. A user interface may hide an administrative button, but the backend must still enforce authorization. The same applies to record identifiers: knowing a record’s identifier must not by itself grant access. OWASP’s API Security Project identifies authorization, authentication, resource consumption and related design problems as important risks.
Use encrypted transport for sensitive communication and verify the intended server identity. Transport encryption does not replace application-level access control. A well-protected connection may still carry an unauthorized operation if the server’s policy is wrong. Similarly, a VPN cannot correct inappropriate record permissions or insecure application logic.
For developers, a production service needs tests for both allowed and denied operations, validation of input formats, limits on expensive requests and safe handling of errors. Responses and logs should not reveal secrets unnecessarily. External service responses must be treated as data requiring validation, not as inherently trustworthy instructions. Restrict staff and service credentials to the capabilities genuinely required.
For organizations, maintain a record of deployed endpoints, owners, dependencies and supported versions. Remove obsolete interfaces carefully and review who can access them. A security test must be performed on systems you own or have explicit permission to assess. This guide is a defensive overview, not a testing procedure for third-party systems.
Rate Limits, Pagination, And Reliable Retries
Providers often limit usage to protect service capacity, enforce subscription terms and distribute resources among callers. Limits can be measured per time window, project, user or operation. One API might permit a burst of requests but restrict sustained activity; another may assign different costs to different operations. Check the current contract rather than assuming a universal requests-per-minute value.
Pagination divides large result sets into manageable pages. A response might provide a link to the next page, an opaque cursor, or a documented page number. Clients should follow the provider’s pagination mechanism and understand whether the dataset may change during traversal. Do not assume that receiving a first page means the complete dataset has been retrieved.
If a provider reports rate limiting or maintenance, use supported delay guidance. For example, GitHub’s rate-limit documentation describes reset information, retry timing and progressively longer delays for continued failures. Other providers may use different response headers and policies. Avoid aggressive repeated requests and set a reasonable stopping condition.
For a state-changing request with an unknown result, check the documented operation status before retrying. A provider may support an idempotency key that lets it recognize repeated submissions for the same intended operation. Such functionality must be explicitly supported and used according to its contract. Without it, a retry after a lost response could create a second order. Design the client to distinguish temporary network problems from permanent input or permission errors.
Webhooks And Event-Driven Workflows
Polling means asking a service at intervals whether something has changed. A webhook allows a provider to send a notification to a receiving service when a relevant event occurs. This can reduce unnecessary requests and improve responsiveness, although delivery still depends on the infrastructure and configured policies.
Imagine an online store waiting for a confirmed shipment event. The carrier could notify the store’s backend when a package status changes. The store verifies that the notification originated from the carrier according to the provider’s documented signing method, checks whether the event is relevant and updates its own record. It should not expose secret tokens or trust arbitrary messages simply because they arrive at the configured address.
Real delivery systems may send notifications more than once, deliver them late or deliver events in a different sequence from the original actions. A receiving application should handle duplicate identifiers where provided and avoid triggering repeated irreversible actions. For important business information, reconcile the final state with the authoritative service rather than assuming the last notification tells the entire story.
Not all APIs offer webhooks. Some integrations use queues, subscriptions or periodic synchronization. Choose a pattern that matches the provider’s actual behavior and the business requirement. A low-frequency data refresh may be perfectly adequate for a static directory, while a payment workflow needs a carefully verified completion process.
Why APIs Matter For Businesses And Automation
APIs allow organizations to combine specialized capabilities rather than building every component themselves. A small online retailer may integrate inventory software, its payment service and shipping provider. A successful order can trigger accounting updates, stock reservations and fulfillment tasks. Each step requires clearly defined permissions and error handling, not just a connection between applications.
This modular approach can reduce initial development work but introduces dependencies. If a provider experiences an outage, changes pricing or retires a capability, the business may need to modify its own workflow. Record which operations are essential, what alternatives exist and how the organization can continue working during service disruption. The cloud computing guide provides useful context for services hosted outside an organization’s own equipment.
Costs may relate to requests, transferred data, subscription features or underlying operations. An integration that retrieves the same large dataset repeatedly can waste capacity and create avoidable bills. Appropriate caching, pagination and change notifications may reduce waste when the provider permits them. Respect data freshness requirements and contractual restrictions.
The value of an API is measurable in the work it enables. A stable interface with excellent documentation, predictable errors and responsive support may be more valuable than a fashionable architecture that nobody can maintain. Evaluate the entire integration lifecycle, including recovery and exit planning.
How To Read API Documentation As A Beginner
Start with the overview and identify what the service can actually do. Look for the official base address, supported versions and access requirements. Read a single endpoint from beginning to end before copying examples. Identify its required parameters, optional parameters, supported request methods, input format and expected output.
Next review the authentication instructions and any costs or limits. Determine whether a test environment is available. A sample request in documentation is not necessarily safe to send to a production account, especially if it creates, modifies or deletes something. Prefer an authorized read-only example or sandbox while learning. Never include real credentials in public notes or example code.
Check the error definitions and the meaning of response fields. For a date or currency, look for the documented format and unit. For a paginated list, look for the mechanism that reveals remaining results. For a long-running action, find out whether the response confirms completion or merely confirms acceptance.
Finally, keep records of the supported version and relevant change notices. A tutorial may describe an older version of the service even if the broad principle remains useful. Verify current documentation before using an example in production. This simple reading sequence will save more time than memorizing code snippets whose assumptions you do not understand.
Practice API Requests And Responses Offline
A beginner does not need an account, internet connection or API key to understand the request-and-response concept. Use the sample Greenfield Library interface below. It offers a read operation for book 42. The request target is /books/42, and the documented response contains an identifier, a title and an availability flag. Read the request and response below to practice interpreting the messages offline.
The response body is deliberately small. If the book record exists and the caller can see it, the service returns its public fields. The application reads the title and represents the boolean availability flag as a human-friendly message. If the book is absent, the service can return a documented not-found response. If the user tries to borrow the book, that would require a separate authorized operation.
Think through three possible situations: the request succeeds, the resource does not exist, and the network times out. In the first condition, display the validated result. In the second, show the appropriate absence message rather than retrying indefinitely. In the third, explain the connection problem and follow the service’s retry policy. This is the conceptual foundation of an API client.
An actual integration must also consider TLS, timeouts, response validation, account permissions, and the provider’s terms. The offline exercise avoids these operational dependencies so readers can focus on the exchange itself.
GET /books/42 HTTP/1.1
Host: library.example
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 42,
"title": "The Garden of Ideas",
"available": true
}Troubleshooting An API Integration
Begin by determining whether the problem occurs before a request is sent, while establishing a network connection, after the service returns a response, or during local processing of the result. An application’s error message may combine several possibilities into one notification. Record the exact time, authorized endpoint, method, status code and a redacted error description when available.
If no response arrives, check underlying internet connectivity and the service’s official status information. Name resolution, connection timeout or certificate problems require different investigations from a permission failure. Do not accept invalid TLS certificates or change security settings globally as a shortcut. If an authorized workplace VPN is required, confirm its expected connection status using the VPN guide and the organization’s instructions.
If a response arrives but the application fails to display it, inspect the expected format and allowed fields. An access token may have expired, a version may have changed, a required query parameter may be missing, or an optional field may be absent. Test with non-sensitive sample data and follow the relevant official error documentation.
Avoid publishing complete request logs that may include credentials, private user information or confidential order details. Redact sensitive headers and data first. Escalate persistent provider failures using the service’s official support channel. A clear diagnostic record helps distinguish a genuine outage from a defect in the integration.
Versioning, Compatibility, And Long-Term Maintenance
An API is a contract used by software that may not be updated simultaneously. Adding a new optional field can be compatible with many clients, while removing a required field or changing its meaning may break them. Whether a change is compatible depends on the original contract and how clients validate and interpret data.
Providers may use versioned paths, request headers, separate schemas or another documented strategy. The absence of a version number in a URL does not mean compatibility is guaranteed. Some services evolve gradually without conventional version numbers, but their callers still need to understand changes in behavior and scheduled removals.
Maintain integration tests that exercise ordinary success cases, expected errors and boundary conditions. Use authorized environments with synthetic records. When a provider announces retirement of a feature, assess affected operations and plan migration before its deadline. Keep dependencies, configuration and secrets under appropriate maintenance procedures.
An effective integration also has an owner who understands the business purpose, the recovery plan and the source documentation. Software remains useful not merely because it connects successfully today, but because future maintainers can understand and operate it responsibly.
API Documentation And References
Consult the provider’s documentation before using a live API, particularly for sensitive or state-changing operations.
Frequently Asked Questions
What Is An API In Simple Terms?
An API is an agreed interface that lets software request capabilities or information from other software without needing to know its internal implementation.
Does Every API Use The Internet?
No, operating systems and software libraries also offer APIs that work locally. Web APIs communicate over networks.
What Is An API Endpoint?
For a web API, an endpoint is a documented address associated with an available operation or resource.
What Is The Difference Between REST And GraphQL?
REST is an architectural style commonly expressed through HTTP resources. GraphQL uses a typed schema and lets clients select fields through queries.
What Is JSON?
JSON is a text-based data format for structured values such as objects, arrays, strings, numbers, booleans and null.
Are APIs Free?
Some are free for permitted uses; others charge by subscription, operation or usage. Check the actual provider’s terms.
Is An API Key A Password?
It depends on the key’s purpose. Secret keys can grant powerful application access and must be protected. Public identifiers have different intended security properties.
What Is An API Rate Limit?
A provider’s restriction on request frequency or resource usage. Respect documented limits and retry instructions.
Can I Learn APIs Without Coding?
Yes, you can learn the contract, request, response and error concepts with diagrams and sample messages before writing a client.
Why Do APIs Stop Working?
Potential causes include connection failures, changed versions, expired credentials, insufficient permissions, malformed requests, rate limits and service outages.



