REST API usually means an HTTP service that exposes resources through URLs and standard methods such as GET, POST, PUT, PATCH, and DELETE. REST itself is a set of architectural constraints for efficient, reliable, scalable distributed systems; many services called REST APIs use HTTP conventions without satisfying every REST constraint. This glossary explains the terms, status codes, authentication rules, retry behavior, and OpenAPI concepts you need to design and consume one correctly.
REST and HTTP: the foundation
A REST request identifies a target resource, chooses an HTTP method, and may include parameters, headers, and a body. The server returns a status code, headers, and usually a representation such as JSON. A resource-oriented design models things that exist or can be acted on: /users/42, /orders/918, or /reports/2026-09.
REST is not synonymous with “JSON over HTTP.” JSON is a representation choice. An API can return JSON while still violating REST constraints, and an HTTP API can be useful without being strictly RESTful. Treat “REST API” as practical shorthand unless the service documents which constraints it implements.
HTTP method glossary
| Method | Purpose | Safety and idempotency | Typical example |
|---|---|---|---|
GET |
Retrieve a representation of a target resource. | Safe and idempotent. | GET /users/42 |
HEAD |
Retrieve the metadata a GET would return, without its body. | Safe and idempotent. | Check size or cache headers before downloading. |
POST |
Submit content for resource-specific processing; often creates state. | Not guaranteed idempotent. | POST /orders |
PUT |
Replace the current representation at a target URI with the request content. | Idempotent by intended effect. | PUT /users/42 |
PATCH |
Apply a partial modification. | Not guaranteed idempotent. | PATCH /users/42 |
DELETE |
Delete the target resource. | Idempotent by intended effect. | DELETE /users/42 |
OPTIONS |
Describe communication options supported by the target. | Safe and idempotent. | Discover allowed methods or support CORS preflight. |
CONNECT |
Establish a tunnel to the server identified by the target. | Not normally an application-resource operation. | Proxy tunnel setup. |
TRACE |
Perform a message loop-back test. | Diagnostic; commonly disabled for security. | Inspect intermediary handling. |
PUT versus PATCH
Use PUT when the request represents the complete replacement at a known URI. Omitting a field can therefore mean removing it, depending on the contract. Use PATCH when the request describes only changes. PATCH is not automatically safe to retry: applying an increment operation twice, for example, can produce two increments. Define the patch document format and concurrency behavior in the API contract.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
#1 Best Overall
- Read Before You Buy — No Video Output: These adapters support charging and USB 2.0 data transfer, but cannot transmit video signals. Except for standard USB webcams (which use USB data only), they are not compatible with HDMI/DisplayPort cables, video-capable USB-C hubs, or docking stations with video output.
- Convert USB-A Ports to USB-C: Designed to connect USB-C earphones, cables, flash drives, card readers, and other USB-C accessories to standard USB-A ports. Plug-and-play with no drivers or software required.
- Aluminum Alloy Housing: Built with a sturdy aluminum alloy shell that aids in heat dissipation and protects against daily wear and scratches. Designed to maintain a stable and secure connection.
- Compact & Travel-Friendly: The ultra-compact design allows the adapter to stay plugged into your device without blocking adjacent ports or adding bulk, reducing wear and tear on your original USB ports.
- 12-Month Warranty: Backed by a 12-month manufacturer warranty for peace of mind. Designed to meet strict quality control standards for reliable everyday performance.
Safe methods, idempotency, and retries
A safe method does not request a state change. Idempotency means that repeating identical requests has the same intended server effect as sending one request. It does not require identical response bodies, timestamps, or status codes: a first DELETE may return 204 and a repeat may return 404 while the intended end state remains “resource absent.”
GET, HEAD, OPTIONS, and TRACE are safe and idempotent under HTTP semantics. PUT and DELETE are idempotent but not safe. POST and PATCH are not guaranteed idempotent. Retry only when the operation and failure mode justify it. For non-idempotent creation, an API may define an idempotency-key header so the server can associate retries with one logical operation; that behavior must be documented by the API owner.
- Retry transient network failures and selected 5xx responses with bounded exponential backoff and jitter.
- Do not blindly retry validation errors, authentication failures, or a request that may have succeeded when the operation can create duplicates.
- Honor
Retry-Afterwhen supplied, especially for rate limiting.
HTTP status-code glossary
The first digit identifies the class: 1xx informational, 2xx successful, 3xx redirection, 4xx client error, and 5xx server error. Valid HTTP status codes range from 100 through 599. Clients should understand the class even when they do not recognize an individual code.
Rank #2
- 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
- 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
- Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
- 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
- What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.
| Code | Use it when | Implementation note |
|---|---|---|
| 200 OK | The request succeeded and a representation or result is returned. | Document the response schema. |
| 201 Created | The request created one or more resources. | Normally identify the new resource with Location or the target URI. |
| 202 Accepted | Processing was accepted but is not complete. | Return a way to check job state when work is asynchronous. |
| 204 No Content | The operation succeeded and no representation is needed. | Do not send a response body. |
| 400 Bad Request | Syntax or input prevents the server from fulfilling the request. | Return a stable, machine-readable error format. |
| 401 Unauthorized | Credentials are missing, invalid, or not supplied. | Challenge with WWW-Authenticate when applicable. |
| 403 Forbidden | Credentials are understood but lack permission. | Do not use it merely for a missing login. |
| 404 Not Found | The target resource cannot be found. | Decide whether hidden resources should appear as 404 for security. |
| 409 Conflict | The request conflicts with current resource state. | Define the specific conflict and recovery action. |
| 429 Too Many Requests | The client exceeded a documented rate limit. | Provide limits and, when possible, Retry-After. |
| 500 Internal Server Error | An unexpected server condition prevented completion. | Do not expose secrets; correlate the failure with a server-side request ID. |
401 versus 403: authentication and authorization
Authentication answers “Who are you?” Authorization answers “May that identity perform this action?” A protected origin commonly responds to missing or invalid credentials with 401 and a WWW-Authenticate challenge. The client then sends credentials in Authorization, such as a bearer token. When those credentials are valid but insufficient for the requested resource, use 403.
Send credentials only over a confidential connection. Never put long-lived secrets in URLs, logs, browser history, or source control. OpenAPI 3.1 can describe HTTP authentication, API keys in headers, cookies or query parameters, mutual TLS, OAuth 2.0 flows, and OpenID Connect Discovery.
Representations, parameters, and request bodies
Parameters
A path parameter identifies a resource (/users/{id}); a query parameter modifies a collection request (?limit=20&status=active); a header carries metadata or credentials; and a cookie carries state for cookie-based clients. Document type, requiredness, allowed values, defaults, and encoding.
Rank #3
- Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
- Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
- Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
- Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
- What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.
Request and response representations
A request body contains content sent for an operation, commonly JSON. Use Content-Type to declare its format and Accept to state which response formats the client can process. Keep field names, nullability, date formats, pagination envelopes, and error structures consistent across endpoints.
Pagination, filtering, and caching
Project-specific conventions are not defined by REST or HTTP. Choose and document cursor- or page-based pagination, maximum page size, stable ordering, filter syntax, and whether deleted records appear. For cacheable representations, document Cache-Control, validators such as ETag, and conditional requests using If-None-Match or If-Modified-Since. A 304 response tells a client its cached representation remains valid.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchOpenAPI: the executable contract
OpenAPI describes an HTTP API in a machine-readable document. An operation is one method-and-path action, such as GET /users/{id}. A parameter is input in a path, query, header, or cookie. A request body defines content sent to the operation. A response object documents an outcome keyed by an HTTP status code; OpenAPI permits any HTTP status code as that key. A security scheme declares HTTP auth, an API key, mutual TLS, OAuth 2.0, or OpenID Connect. A schema defines data shape and constraints.
Rank #4
- Dual Converters, Infinite Potential：Includes 2× USB C male to USB A female adapters and 2× USB A male to USB C female adapters. Perfect for a wide range of uses—tablets with Bluetooth keyboards, expand USB ports on macbook, and more. Two different converters for all your daily needs
- Next-Level 10Gbps & 3A Charging: No more slow 480Mbps, this usb to usb c adapter has a transfer speed of up to 10Gbps, allowing you to do more transferring in less time. This usb adapter fits both USB A and USB C charger, supporting up to 3A fast charging
- Upgraded Exquisite Craftsmanship: With an aluminum alloy housing and metal connector, the usbc to usb adapter is extremely durable and sturdy. Rigorously tested to withstand more than 10,000 times of plugging and unplugging, ensuring long-lasting performance
- Broad Compatible: The usb c to usb adapter widely supports all USB C/ USB A devices like laptops, tablets, cellphones, car chargers, and phone chargers. Such as compatible with MacBook Pro/Air 2023/2022, Thunderbolt 4/3 Devices,Apple MagSafe Watch 9/8/7/SE/Ultra, iPad Pro 2022/2021, Samsung Galaxy S23/S20/S10, and iPhone 17/16/15 Pro. Plug and play
- Please Note: To reach 10Gbps speed, keep the cable under 3.3 ft. For USB A Male to USB C adapters, try flipping the USB C connector. USB C Male to USB A adapters support bidirectional 10Gbps transfer within 3.3 ft
Use the contract to generate documentation, client types, validation, mock servers, and tests. Keep it synchronized with implementation: an endpoint that returns 202 in production but is documented only as 200 creates client bugs. Define error envelopes, pagination, versioning, and deprecation policy explicitly because OpenAPI does not choose those rules for you.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Calling a REST endpoint
cURL
curl -H "Accept: application/json"
-H "Authorization: Bearer $TOKEN"
"https://api.example.com/v1/users/42"Python
import os
import requests
r = requests.get(
"https://api.example.com/v1/users/42",
headers={"Accept": "application/json", "Authorization": f"Bearer {os.environ['TOKEN']}"},
timeout=30,
)
r.raise_for_status()
user = r.json()Node.js
const res = await fetch('https://api.example.com/v1/users/42', {
headers: { Accept: 'application/json', Authorization: `Bearer ${process.env.TOKEN}` }
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const user = await res.json();Common design and integration failures
- Wrong status code: map the actual condition to the documented HTTP semantics; do not return 200 with an error hidden in JSON.
- 401/403 confusion: challenge missing or invalid credentials with 401; use 403 for an authenticated identity without permission.
- Duplicate writes after retries: use PUT where replacement semantics fit, or implement the service’s documented idempotency-key behavior for POST.
- Unexpected empty fields: distinguish omitted, null, and empty values in the schema and PATCH rules.
- Rate-limit loops: stop or back off on 429 and honor
Retry-Afterinstead of retrying immediately. - Contract drift: run contract tests and review OpenAPI changes whenever handlers, schemas, or status codes change.
- Credential leakage: redact authorization headers and query strings from logs and use TLS.
Or skip the browser setup
When a REST workflow needs website screenshots, ScreenshotNeo provides a single HTTP endpoint rather than a browser-installation project. It accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each cleanup step can be disabled. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers report the page verdict and billing result. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.
Example using the documented API at ScreenshotNeo docs:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpThere is a free allowance of 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 shots, and every feature is included on every plan. Create a free ScreenshotNeo account.
Best Value
- 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
- Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
- Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
- HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
- What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.
Frequently Asked Questions
Is every HTTP API RESTful?
No. “REST API” is often used informally for an HTTP service; strict REST requires a broader set of architectural constraints.
Can a 204 response contain JSON?
No. 204 means the operation succeeded with no response content, so clients should not expect a body.
Should a missing resource return 401 or 404?
Use 401 when credentials are missing or invalid. Use 404 when the target does not exist, subject to your documented security policy.
Free tools Windows power users keep installed
One-click scans. No signup required.
Does OpenAPI enforce my implementation automatically?
No. OpenAPI documents the contract; validation, generated tests, gateways, or middleware are needed to enforce it.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
