What Is an API? A Practical Guide to APIs, REST, Endpoints, and Calls

API stands for application programming interface. It is a documented contract of rules, operations, inputs, and outputs that lets one piece of software use another piece of software without knowing its internal implementation. The API defines how to ask for a capability and what response or error to expect.

An API can be a local library function, a browser capability such as geolocation, or a remote web API reached over HTTP. A web API commonly exposes endpoints, accepts methods and parameters, and returns data such as JSON or XML. REST is one architectural style for web APIs; it is not a synonym for every API.

Sources: IBM’s API definition, MDN’s API glossary, and the NIST CSRC glossary.

What does API stand for?

API means application programming interface:

• Application: a program or software component.
• Programming: interaction happens through code.
• Interface: a defined boundary and set of rules.

NIST describes an API as a system access point or library function with well-defined syntax that user code can access for well-defined functionality. MDN describes it as features and rules inside software that enable interaction through software rather than a human interface.

How an API works

1. Discover the contract. Read documentation for operations, parameters, authentication, schemas, limits, and errors.
2. Build a request. A caller selects an operation and supplies its inputs. For a web API this normally includes an HTTP method, endpoint URL, headers, query parameters, and sometimes a body.
3. Validate and authorize. The provider checks syntax, credentials, permissions, and input values.
4. Run the operation. Internal services, databases, or libraries perform the requested work.
5. Return a response. The response includes a status and either data or an error. The format and fields are part of the contract.

An endpoint is the location where an API receives calls for a resource or operation. See IBM’s explanation of API endpoints.

Request anatomy

GET https://api.example.com/v1/customers/42?include=orders
Authorization: Bearer YOUR_TOKEN
Accept: application/json

• GET is the HTTP method.
• https://api.example.com/v1/customers/42 is the endpoint.
• include=orders is a query parameter.
• Authorization is a request header.
• Accept tells the server which response representation the client can read.

Response anatomy

HTTP/1.1 200 OK
Content-Type: application/json

{"id":42,"name":"Ada Lovelace","orders":[]}

A failed call is also a defined response. For example, a missing credential may produce an authentication error, while an invalid field may produce a validation error. Do not assume status codes or error fields are identical across providers; use that API’s documentation.

Types of APIs

Local library APIs

A language library exposes functions, classes, and modules as an API. A string method or file API can run entirely inside your process and requires no network request. This follows NIST’s broad definition of an API.

Browser APIs

Browsers expose capabilities such as Geolocation, media capture, and Web Animations to web code. The browser implements the capability; your code uses the documented interface. Permissions and browser support are part of the contract.

Web APIs

A web API is a remote interface exposed over a network, commonly through HTTP. The service publishes endpoints, methods, authentication rules, request schemas, response formats, and errors.

Private, partner, and public APIs

A private API is used inside an organization. A partner API is shared with selected external organizations. A public API is documented for broad external use. Access policy, credentials, quotas, and terms differ by provider.

What is a REST API?

REST (representational state transfer) is an architectural style for designing web APIs. REST APIs commonly model resources and use HTTP methods such as GET, POST, PUT, and DELETE. The specific service defines method behavior, status codes, authentication, pagination, and error structure.

REST does not require JSON. JSON and XML are common representations, but an API can return other representations when its contract specifies them. IBM’s REST API overview explains the style and its design principles.

Method	Common intent	Important caveat
GET	Read a resource	Exact caching and side-effect behavior belong to the API contract.
POST	Create a resource or trigger an operation	Request body and response vary by service.
PUT	Replace or update a resource	Some APIs use PATCH for partial updates.
DELETE	Remove a resource	Deletion may be soft, asynchronous, or restricted.

API endpoint, route, and base URL

A base URL identifies the API service, such as https://api.example.com/v1. An endpoint adds a path for a resource or operation, such as /customers/42. A route is the server-side mapping that handles a method and path. Documentation may use these terms differently, so follow the provider’s definitions.

Version prefixes such as /v1 are one way to communicate compatibility boundaries. Never infer that a version is permanently supported; read the provider’s lifecycle and migration documentation.

Runnable API call examples

The following examples call a generic JSON endpoint. Replace the URL, token, fields, and response handling with the contract for the API you use.

cURL

curl --fail-with-body \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Accept: application/json" \
  "https://api.example.com/v1/customers/42"

Python

import os
import requests

url = "https://api.example.com/v1/customers/42"
headers = {
    "Authorization": f"Bearer {os.environ['API_TOKEN']}",
    "Accept": "application/json",
}
response = requests.get(url, headers=headers, timeout=30)
response.raise_for_status()
customer = response.json()
print(customer)

Node.js

const token = process.env.API_TOKEN;
const res = await fetch('https://api.example.com/v1/customers/42', {
  headers: {
    Authorization: `Bearer ${token}`,
    Accept: 'application/json'
  }
});
if (!res.ok) {
  throw new Error(`API request failed: ${res.status} ${await res.text()}`);
}
const customer = await res.json();
console.log(customer);

Authentication and authorization

Authentication identifies the caller; authorization determines what that caller may do. Common schemes include API keys, bearer tokens, OAuth access tokens, signed requests, and mutual TLS. The scheme, header name, token scope, expiration, and rotation process are implementation-specific.

• Keep credentials in environment variables or a secret manager.
• Send credentials only to the documented host over HTTPS.
• Give tokens the smallest scope needed.
• Redact authorization headers and secrets from logs.
• Plan for expiration, rotation, and revocation.

Parameters, schemas, and content types

Query parameters filter, paginate, sort, or modify a request. Path parameters identify a resource. Headers carry metadata such as authorization and content negotiation. A body carries structured input, commonly with Content-Type: application/json.

curl -X POST "https://api.example.com/v1/orders" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"customer_id":42,"items":[{"sku":"book-1","quantity":1}]}'

Validate required fields, allowed values, lengths, formats, and nesting before sending. A schema in documentation or an OpenAPI description can make this machine-readable.

Documentation and OpenAPI

Documentation is the practical instruction set for callers. It should identify operations, parameters, authentication, request and response schemas, examples, limits, and errors. OpenAPI is a specification for describing an HTTP API; it is not the API service itself. Tools can use an OpenAPI document to generate clients, validate requests, and expose interactive reference pages.

API versus web service

Concept	Meaning
API	Any documented software interface, local or remote.
Web API	An API exposed over a network, commonly with HTTP.
Web service	A network-accessible software service; usage varies by context and may imply particular standards.
REST API	A web API designed around REST principles.

Every REST API is an API, but APIs also include local libraries and browser interfaces. A web service may use REST, another HTTP design, or a different protocol.

Reliability, performance, and cost

Reliability checklist

• Set connect and overall timeouts.
• Retry only transient failures such as documented rate limits or temporary server errors.
• Use exponential backoff with jitter and cap retry count.
• Make writes idempotent when the provider supports idempotency keys.
• Record request IDs, status codes, latency, and safe error details.
• Handle pagination and partial failures explicitly.

Performance checklist

• Request only fields you need when field selection exists.
• Use pagination rather than downloading unbounded collections.
• Reuse HTTP connections through a session or keep-alive agent.
• Cache responses only when freshness and authorization rules permit.
• Batch operations when the API offers a documented batch endpoint.
• Measure latency from your deployment region; do not assume a provider’s average.

Cost checklist

API cost can depend on requests, records, compute time, data transfer, or plan limits. Read current pricing and quota documentation, then estimate peak and average usage. Cache safe reads, avoid accidental retry storms, and monitor usage before approaching a quota. Commercial terms are specific to each provider.

Troubleshooting common API errors

Symptom	Likely cause	Fix
401 Unauthorized	Missing, expired, or malformed credentials.	Check the documented authentication header, token value, host, and expiration.
403 Forbidden	Credentials are valid but lack permission or scope.	Request the required scope or use an authorized account.
404 Not Found	Wrong base URL, version, path, or resource ID.	Copy the endpoint from current documentation and verify the identifier.
400 or 422	Invalid parameters or request schema.	Inspect the error body, validate types and required fields, and send the documented content type.
405 Method Not Allowed	HTTP method does not match the operation.	Use the method documented for that endpoint.
409 Conflict	State conflict or duplicate operation.	Refresh resource state and follow the provider’s conflict or idempotency guidance.
429 Too Many Requests	Rate limit exceeded.	Honor retry headers, slow callers, add backoff, and review quota options.
5xx or timeout	Temporary provider or network failure.	Use bounded retries for safe operations, capture request IDs, and check service status.
Unexpected JSON or empty body	Wrong content negotiation, error response, or endpoint.	Check status before parsing, inspect Content-Type, and log a bounded response body.

Or skip the browser setup

If your API use case is collecting website screenshots, ScreenshotNeo provides a website screenshot API and MCP server. A single GET request returns PNG, JPEG, WebP, or PDF. Cookie and consent banners are accepted and 60+ known consent platforms, newsletter popups, and chat widgets are removed before capture; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the result with X-Page-Verdict and X-Billed headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients.

See the ScreenshotNeo API documentation for all options.

cURL

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

Node.js

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Options include full-page capture with lazy images loaded, CSS-element capture, dark mode, 12 device presets and custom viewports, retina scale, PDF paper settings and page ranges, HTML/CSS rendering, custom JavaScript and CSS, clicks, waits, ad and tracker blocking, custom headers and cookies, timezone and geolocation, transparent backgrounds, resizing, chosen cache TTLs, signed links, asynchronous jobs with signed webhooks, bulk capture for 100 URLs per call, usage reporting, and an OpenAPI specification. Parameter names used by other screenshot APIs also work, which can simplify migration.

Plans include 1,000 shots per month free with no card; paid plans start at $5 for 3,000 shots. Yearly billing gives two months free, and every feature is on every plan. Create a free ScreenshotNeo account.

FAQ

Is an API only used over the internet?

No. Library functions and browser capabilities are APIs too. Remote web APIs are one category.

Does every API use HTTP?

No. HTTP is common for web APIs, while local APIs and other network protocols use different mechanisms.

Is REST the same as an API?

No. REST is an architectural style for web APIs. The word API includes many interfaces that are not REST.

What is an API key?

An API key is one provider-defined way to identify or authorize a caller. Its permissions, format, and security requirements depend on the service.

Where should I start when integrating an unfamiliar API?

Read the authentication, quick-start, endpoint, schema, error, pagination, quota, and versioning sections, then make one small request with a timeout and safe logging.