Types of APIs: A Complete Guide

API types overlap across several dimensions. REST, SOAP, GraphQL and gRPC describe architectural or protocol styles. Request/response, streaming, WebSockets, webhooks and event messaging describe how communication is delivered. Public, private, partner and composite APIs describe who can use an API and how operations are combined.

For most public CRUD services, start with REST. Choose GraphQL when clients need different slices of a connected data graph. Choose gRPC for controlled internal services that need generated clients, strong typing or streaming. Use SOAP when an existing enterprise contract or WS-* policy requires it. Use WebSockets for continuous, low-latency, two-way updates. Add webhooks or event messaging when the server must notify clients asynchronously.

What does “API type” mean?

“API type” is not one mutually exclusive taxonomy. A single product can expose a public REST API, call internal services over gRPC, publish webhooks for asynchronous work and maintain a WebSocket connection for live updates.

Dimension	Examples	Question it answers
Architecture or protocol	REST, SOAP, GraphQL, gRPC	How are operations and messages modeled?
Connection and delivery	Request/response, streaming, WebSocket, webhook, event bus	Who sends data, and does the connection stay open?
Exposure	Public, private, partner	Who is allowed to call it?
Composition	Composite API	How many backend operations are combined into one client request?

REST APIs

REST (Representational State Transfer) models data as resources identified by URLs. HTTP methods express operations: GET retrieves, POST creates, PUT replaces, PATCH partially updates and DELETE removes. Requests are designed to be stateless, so each request carries the context needed to process it.

Example

GET /v1/customers/42 HTTP/1.1
Host: api.example.com
Authorization: Bearer TOKEN
Accept: application/json

A REST response commonly uses JSON, an HTTP status code and headers such as Cache-Control, ETag and Content-Type.

When REST fits

Public APIs used by browsers, mobile apps and third-party developers.
CRUD workloads with clear resources.
Systems that benefit from HTTP caching, proxies and familiar tooling.
Teams that want OpenAPI documentation and generated clients.

REST design decisions

Use nouns for resource paths, such as /orders, rather than verbs such as /createOrder.
Use status codes consistently: 200 for success, 201 for creation, 204 for a successful empty response, 400 for invalid input, 401 for missing or invalid authentication, 403 for insufficient permission, 404 for a missing resource, 409 for a conflict and 429 for rate limiting.
Make retries safe with idempotency keys for operations such as payments or order creation.
Define pagination, filtering, sorting and error formats before implementation.
Plan versioning before a breaking change. URL versions, headers and compatible additive changes are common choices.

GraphQL APIs

GraphQL is a query language and strongly typed schema model. The client selects the fields it needs, including related data, through one schema. Queries read data, mutations write data and subscriptions deliver real-time updates.

query ProductPage($id: ID!) {
  product(id: $id) {
    id
    name
    price
    reviews(first: 5) {
      nodes { rating comment }
    }
  }
}

GraphQL can reduce over-fetching and round trips, especially for mobile clients and frontends that aggregate connected data. The server must still enforce authorization for every field or resolver, validate query depth and cost, paginate collections and control introspection in production.

When GraphQL fits

Different clients need different fields from the same domain graph.
Related resources must be fetched in one request.
A frontend team needs a typed contract that evolves additively.

GraphQL trade-offs

HTTP cache behavior is less automatic because many queries use POST.
Resolver chains can create N+1 database calls without batching.
Unbounded queries can consume excessive CPU or database time.
Subscriptions require a separate long-lived transport and operational model.

Use the GraphQL documentation for schema design, validation, authorization, pagination, caching and security guidance.

gRPC APIs

gRPC is an RPC framework. Services declare methods, parameters and return types, commonly in Protocol Buffers. Code generation creates typed client and server stubs, so a client calls a remote method through an interface that resembles a local object.

service Inventory {
  rpc GetStock (StockRequest) returns (StockReply);
}

message StockRequest { string sku = 1; }
message StockReply { int32 available = 1; }

gRPC supports unary calls, server streaming, client streaming and bidirectional streaming. Protocol Buffers provide compact serialization and explicit schemas.

When gRPC fits

Internal service-to-service calls where your organization controls both ends.
Low-latency or high-throughput workloads.
Polyglot microservices that benefit from generated clients.
Streaming data between trusted services.

gRPC constraints

Browser clients generally need gRPC-Web or a gateway.
Binary payloads are less convenient to inspect manually than JSON.
Load balancers, proxies, observability and retry policies must support HTTP/2 and long-lived streams.

See the official gRPC core concepts for service definitions, generated stubs and streaming types.

SOAP APIs

SOAP is an XML messaging protocol with an extensible envelope and formally defined processing rules. The W3C SOAP 1.2 specification describes it as a protocol for exchanging structured information in distributed environments.

<soap:Envelope xmlns:soap='http://www.w3.org/2003/05/soap-envelope'>
  <soap:Body>
    <GetAccount xmlns='https://example.com/accounts'>
      <AccountId>42</AccountId>
    </GetAccount>
  </soap:Body>
</soap:Envelope>

SOAP remains useful when an enterprise integration already depends on WSDL contracts, XML schemas, WS-Security, transactions or other WS-* policies. It is usually a poor fit for a new lightweight public API when simpler HTTP and JSON conventions are sufficient.

WebSocket APIs

The WebSocket API opens a two-way interactive session between a browser and server. After the connection is established, either side can send messages without polling.

const socket = new WebSocket('wss://api.example.com/updates');
socket.addEventListener('open', () => {
  socket.send(JSON.stringify({ type: 'subscribe', topic: 'orders' }));
});
socket.addEventListener('message', event => {
  const update = JSON.parse(event.data);
  console.log(update);
});

Good WebSocket use cases

Chat and presence.
Collaborative editing.
Live dashboards and operational monitoring.
Games and live financial feeds.

Operational costs

Persistent connections require connection tracking, heartbeat and reconnect logic, coordinated load balancing and capacity planning for connection counts. The stable browser WebSocket interface has no built-in backpressure; a fast producer can overwhelm a slow consumer. MDN documents WebSocketStream as a backpressure-aware alternative, but browser support is limited.

Request/response, streaming, webhooks and events

Request/response

The client sends a request and waits for one response. REST, SOAP, GraphQL and unary gRPC commonly use this pattern. It is straightforward to authenticate, observe, cache and retry.

Streaming

A stream sends a sequence of values over one request. Use server-sent events when the server primarily pushes text updates over HTTP. Use gRPC streaming for controlled service-to-service links. Use WebSockets when both sides need to send messages continuously.

Webhooks

A webhook is a server-initiated HTTP request sent after an event, such as invoice.paid. Design handlers to verify signatures, acknowledge quickly, deduplicate by event ID and process asynchronously. Retries mean delivery is normally at least once, so handlers must be idempotent.

Event-driven messaging

Queues and event buses decouple producers from consumers. They are useful for fan-out, durable asynchronous work and absorbing traffic spikes. They add broker operations, delivery semantics, schema governance and eventual consistency.

Public, private, partner and composite APIs

Type	Definition	Typical controls
Public or open	Available to external developers.	API keys or OAuth, quotas, documentation, version policy.
Private or internal	Used within one organization.	Service identity, network policy, least-privilege authorization.
Partner	Shared with selected businesses.	Contracts, scoped credentials, allowlists, support agreements.
Composite	Combines several backend operations into one client request.	Dependency timeouts, partial-failure rules, aggregate authorization.

These exposure types can use any protocol. A public REST endpoint may call private gRPC services and emit partner webhooks.

REST vs GraphQL vs gRPC vs SOAP vs WebSocket

Style	Orientation	Typical payload	Connection	Best fit
REST	Resources and HTTP methods	Usually JSON	Request/response	Public CRUD and broad interoperability
GraphQL	Client-selected data graph	Usually JSON	Request/response; subscriptions for live data	Complex connected data and varied clients
gRPC	Typed remote functions	Protocol Buffers	Unary or streaming	Internal, low-latency, strongly typed services
SOAP	Structured XML messages	XML	Usually request/response	Legacy or regulated enterprise contracts
WebSocket	Messages over a persistent channel	Application-defined	Bidirectional and long-lived	Live two-way interaction

JSON, XML and Protocol Buffers are representations or serialization formats. They are not interchangeable names for REST, GraphQL, gRPC, SOAP or WebSocket.

How to choose an API type

Identify the communication shape. If one request produces one result, request/response is simplest. If updates continue, evaluate streaming, WebSockets or events.
Identify the consumers. Public browsers and unknown third parties favor REST or GraphQL. Controlled internal services can use gRPC.
Measure data-shape variability. If every client needs a different connected-data slice, GraphQL can reduce round trips. If resources are stable, REST is easier to cache and document.
Check contract requirements. Existing WSDL, XML schema or WS-* policies can make SOAP mandatory.
Set reliability semantics. Define timeouts, retries, idempotency, ordering, duplicate handling and partial failure behavior.
Plan operations. Confirm that gateways, tracing, metrics, rate limiting, authentication and deployment tooling support the selected transport.

Common combinations

Public REST or GraphQL at the edge, with private gRPC between services.
REST commands that return a job ID, followed by webhooks when processing completes.
REST for account management and WebSocket for live status updates.
GraphQL for product discovery and event messaging for downstream inventory updates.

Production checklist

Write the contract first. OpenAPI is a common choice for REST; schema files serve GraphQL and gRPC; WSDL and XSD define many SOAP integrations.
Document authentication, authorization, request and response formats, errors, limits and runnable examples.
Separate authentication from authorization: authentication identifies the caller; authorization decides what it may do.
Use TLS, rotate credentials and grant only the scopes each client needs.
Set connect, read and overall deadlines. Propagate cancellation through service calls.
Use bounded retries with exponential backoff only for transient failures, and make retried writes idempotent.
Emit correlation IDs, structured logs, latency histograms, error rates and saturation metrics.
Test unit, integration, contract, load and failure scenarios before deployment.
Publish a versioning and deprecation policy before breaking clients.

Using an API to capture screenshots

ScreenshotNeo is a website screenshot API and MCP server from Yorker Media. A GET request returns a PNG, JPEG, WebP or PDF. It accepts the cookie or consent banner before capture and removes more than 60 known consent platforms, newsletter popups and chat widgets. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed; response headers identify the page verdict and whether the request was billed.

See the ScreenshotNeo API documentation for the complete parameter reference.

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

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)

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

Useful capture options

Full-page capture with lazy images loaded, or one element selected by CSS.
Dark mode, 12 device presets, custom viewport and retina scale.
PDF paper size, margins, landscape mode and page ranges.
HTML/CSS to image, custom CSS and JavaScript, and clicking an element before capture.
Hide selectors; wait for a selector, delay or network idle.
Block ads, trackers, requests or resource types.
Custom headers, cookies, user agent and Authorization.
Timezone, geolocation and transparent background.
Image resizing and caching with a chosen TTL.
Signed links for public image tags.
Asynchronous jobs with signed webhooks, bulk capture of up to 100 URLs per call, a usage API and an OpenAPI specification.

Or skip the browser setup

Use the same ScreenshotNeo call when you need production captures without maintaining Playwright or Chromium. Cookie banners, popups and chat widgets are removed before the shot. Bot checks, blank pages and failed loads are never billed. The MCP server lets Claude, Cursor and other MCP clients take screenshots with take_screenshot, inspect pages with get_page_info and create PDFs with capture_pdf. The Free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 shots.

Create a free ScreenshotNeo account.

Troubleshooting

Clients receive 401 or 403

Check that the credential is present, unexpired and sent in the expected header, query parameter or metadata field. Then verify that the credential has permission for the operation and environment.

Requests time out

Set a client deadline and inspect server timing. Reduce payload size, paginate large responses, wait for a specific readiness condition and avoid retry storms. For browser captures, use a selector wait or network-idle wait instead of an arbitrary long delay.

Retries create duplicates

The first request may have succeeded even when the response was lost. Add an idempotency key, store the result by that key and retry only documented transient status codes.

WebSocket messages arrive out of order

Include sequence numbers or event timestamps, detect gaps and request a snapshot when necessary. Reconnect with backoff and resubscribe after authentication.

GraphQL queries are slow

Check resolver fan-out and database query counts. Add batching, field-level authorization checks, pagination and query-cost limits.

gRPC fails through a proxy

Confirm HTTP/2 support, TLS and timeout propagation. If a browser is the caller, use gRPC-Web or expose a suitable gateway.

SOAP rejects an otherwise valid request

Compare namespace URIs, SOAP version, XML schema types, required headers and WS-Security timestamps. Validate against the service’s WSDL and XSD.

Confirm that the target page is reachable without an interactive bot challenge, then wait for the page’s main selector or network idle. With ScreenshotNeo, response headers expose the page verdict and billing status; consent handling and known popup removal run before capture.

Performance, reliability and cost

Performance

Reduce round trips with composite operations where the dependency graph is stable. Use pagination and field selection to limit payloads. Reuse HTTP connections, compress suitable payloads and avoid unbounded GraphQL queries or WebSocket message queues.

Reliability

Define deadlines, retry budgets, idempotency and duplicate handling for every operation. Monitor dependency saturation and distinguish client errors, server errors and timeouts. For asynchronous APIs, persist event IDs and make consumers safe to replay.

Cost

Cost is driven by request volume, compute time, payload size, connection duration, broker retention and third-party calls. Cache immutable or repeatable reads, batch compatible work and set quotas. ScreenshotNeo offers 1,000 free shots per month with no card, then Starter is $5 for 3,000, Growth $15 for 15,000, Pro $39 for 60,000, Scale $99 for 250,000 and Business $249 for 1,000,000. Yearly billing gives two months free, and every feature is available on every plan.

FAQ

Is REST a protocol?

REST is an architectural style that commonly uses HTTP. HTTP is the protocol; JSON is a possible representation.

Can one API use multiple types?

Yes. For example, a public REST API can front internal gRPC services and send webhooks for completed jobs.

Are GraphQL and REST competitors?

They can serve similar clients, but GraphQL is a schema and query model while REST is a resource-oriented architectural style. A system can expose both.

Should every real-time feature use WebSockets?

No. Use server-sent events for mostly one-way updates, webhooks for asynchronous notifications and a message broker for durable event workflows.

When should I replace SOAP?

Replace it only when the existing contract, policy and partner requirements no longer justify it. A migration must account for schemas, security, transactions and client compatibility.