What is an API? It is an interface that lets software use a defined capability without needing to reproduce all the code behind it. When one app displays information from another service, an API often defines what it can ask for and how the reply will be structured.
The definition is broader than online services. A browser, library or operating system can expose APIs too. For a first integration, focus on the contract: what operation is allowed, what information it needs, what it returns and what happens when the request fails.
What is an API in practice?
MDN’s API introduction describes interfaces that make complex functionality accessible through simpler programming constructs. The caller uses the exposed interface rather than taking over the implementation. That boundary lets separate pieces of software cooperate while retaining their own responsibilities.
Imagine a fictional reading-list application showing a book’s availability from a library service. The app needs a documented way to identify a book and interpret the returned availability. It does not need permission to directly browse the library’s internal database or rewrite its lending software.
That separation is useful, but it creates a dependency. The app must handle the interface the service actually provides, including missing data and failures. A beautiful button cannot guarantee that a remote request will succeed, and a successful request does not automatically mean the requested real-world outcome has occurred.
Requests and responses over HTTP
Many web APIs use HTTP. MDN’s HTTP overview explains the client-server exchange: a client initiates a request and the server returns a response. An API defines how that exchange relates to a particular service’s resources and operations.
A request can contain a method, a destination path, headers and parameters or a body. GitHub’s REST API introduction documents these pieces and explains that each endpoint specifies what it requires. Read that endpoint’s documentation instead of assuming a familiar-looking URL accepts the same fields as another service.
Methods commonly distinguish reading from creating or changing information. The exact operation still comes from the documented endpoint. A request body can carry structured data, often JSON, while headers provide information about the request. Neither a JSON object nor a URL alone explains whether an operation is authorized or safe to repeat.
| Part | Question it answers | Example concept |
|---|---|---|
| Method and endpoint | Which operation? | Read a collection |
| Parameters or body | Which input? | Filter by a documented field |
| Authentication | Who is making the request? | Scoped access token |
| Response status | How did the request fare? | Success or error category |
| Response body | What data came back? | Structured records or error details |
Read the response before using it
Do not judge success only by whether your code received a reply. MDN’s status reference distinguishes successful responses, client-side errors and server-side errors. A 404 response and a network connection failure are different observations, even though both might prevent the interface from showing the expected record.
Check the body against the documented format too. A response may contain an empty collection, optional fields or an error description. Parsing JSON establishes that the text can be read as JSON; it does not establish that every field has the type or meaning your application expects.
A fictional reading-list app should distinguish no copies available from no reliable answer received. Showing unavailable after a connection failure could mislead the reader about the library’s stock. Keep an unknown state when the service did not provide enough evidence to decide.
A small read-only code pattern
MDN’s Fetch guide notes that an HTTP error status does not by itself reject the fetch promise. Code needs to inspect the response. The following illustrative function accepts a caller-supplied, documented read-only URL; it was not executed against a service for this article.
async function readJson(url) {
const response = await fetch(url);
if (!response.ok) {
throw new Error('HTTP status: ' + response.status);
}
return response.json();
}This is a learning pattern, not a production integration. It omits timeout handling, schema validation, user-facing error states and provider-specific authentication. Do not paste a privileged token into browser code to complete the example. Begin with public sample data or a provider’s documented test environment.
Permissions and browser rules are separate
Authentication identifies the caller; authorization determines what that caller may do. A token that can read one collection may not be allowed to create or delete records. Use the minimum permissions the task needs, and treat credentials as sensitive rather than copying them into screenshots, public repositories or error reports.
Browser code also encounters cross-origin rules. MDN’s CORS guide explains how response headers control whether a browser permits a page to read certain cross-origin resources. CORS is not a substitute for server-side authorization, and a browser error is not a reason to disable protections indiscriminately.
Describe the failure accurately before changing configuration. Did the server reject credentials, did the browser block access to a response, or was the destination unreachable? These situations require different investigation. Removing a restriction without understanding it can create a security problem while leaving the original integration error unresolved.
Lists, limits and retries need a plan
A collection response may be only one page. GitHub’s pagination guide explains how its API returns subsets and uses response links for additional pages. Other services may use cursors or another documented scheme. Do not interpret the first page as a complete inventory without checking.
Services can also limit request rates. GitHub’s best-practice guidance recommends handling limits and errors deliberately rather than continuing requests blindly. Follow the provider’s wait and retry instructions. A tight retry loop can make an outage or rate-limit problem worse.
Be especially cautious when retrying an action that creates something. If the client times out after sending a request, it may not know whether the server completed the action. Check the provider’s duplicate-prevention or idempotency guidance and the saved result before sending another creation request. An uncertain response is not proof that nothing happened.
Build understanding before automation
- Choose one documented read-only operation and identify its required input.
- Use sample data and the smallest necessary access scope.
- Inspect status, headers and body before displaying the result.
- Validate the fields your app actually depends on.
- Handle empty, unavailable, limited and malformed responses distinctly.
- Check pagination and retry behavior before treating results as complete.
- Add state-changing operations only after understanding their permissions and duplicate risks.
Keep a short integration note describing the endpoint, data needed, expected response and known failure states. This helps the next maintainer understand the dependency without reading every line of code. Include the documentation link and where credentials are managed securely, but never the credential itself.
Agree on what a successful user experience means before connecting services. In the fictional library app, that might mean showing the last confirmed availability with a clear timestamp, or showing a temporary unknown state when fresh information cannot be obtained. Those are product choices to make deliberately, not guarantees supplied by the interface. Discuss how stale information, partial results and temporary failures should appear, and test those cases with sample responses before allowing real users to depend on the connection.
An API makes software cooperation possible by defining a boundary. Reliable integration comes from respecting that boundary: send the documented input, interpret the actual response and handle uncertainty honestly. Once those habits are clear, larger automation becomes easier to reason about without confusing access with correctness.
