HTTP Clients And APIs

What Is An API?

Because an API is an agreement rather than an implementation, it is platform-independent and language-agnostic. A PHP backend can serve a Swift mobile app, a JavaScript frontend, and a Python data pipeline through one contract, and each side can be rewritten without the others noticing, as long as the agreement holds. That is also why shared conventions matter: when everyone reads GET /v1/users the same way, systems built by strangers interoperate without coordination.

A team can invent its own conventions and publish them, and the result is a perfectly usable API. The named styles in this lesson exist because agreeing on someone else's well-documented rules is usually cheaper than teaching the world your own.

One Request, Many Styles

Every web API interaction has the same skeleton: a client sends a request, a server applies it to some data or process, and a response comes back.

PHP example
<?php

declare(strict_types=1);

$interaction = [
    'client sends' => 'a request describing what it wants',
    'server does' => 'reads or changes data, or starts work',
    'server sends' => 'a response with data, confirmation, or an error',
];

foreach ($interaction as $step => $description) {
    echo $step . ': ' . $description . PHP_EOL;
}

// Prints:
// client sends: a request describing what it wants
// server does: reads or changes data, or starts work
// server sends: a response with data, confirmation, or an error

The styles below differ in how the request describes what it wants, how the contract is documented, and who initiates the exchange. They are surveyed here so you can recognize each one; later lessons in this track go deeper on every style.

REST: Resources And HTTP Semantics

REST stands for representational state transfer. It is an architectural style, not a protocol: a set of conventions for building predictable HTTP APIs. Resources are identified by URL paths such as /users/42, standard HTTP methods express intent, and each request stands alone. The server does not remember that a client already asked for the first page of users; the client asks for page two explicitly. That statelessness, plus client and server agreeing only on the contract, is what makes REST APIs easy to cache, scale, and consume from any language.

PHP example
<?php

declare(strict_types=1);

$styles = [
    'REST' => 'GET /v1/users/42 - resource paths plus HTTP methods',
    'RPC' => 'POST /users.deactivate - named commands',
    'SOAP' => 'POST envelope <soap:Envelope> - XML operations with a WSDL contract',
    'GraphQL' => 'POST /graphql - one endpoint, client selects fields',
    'gRPC' => 'UserService.GetUser - generated typed client calls',
];

foreach ($styles as $style => $shape) {
    echo $style . ': ' . $shape . PHP_EOL;
}

// Prints:
// REST: GET /v1/users/42 - resource paths plus HTTP methods
// RPC: POST /users.deactivate - named commands
// SOAP: POST envelope <soap:Envelope> - XML operations with a WSDL contract
// GraphQL: POST /graphql - one endpoint, client selects fields
// gRPC: UserService.GetUser - generated typed client calls

Nothing forces a server to be RESTful. It is a popular convention because it produces APIs that clients can predict, not a rule that requests fail without.

RPC: Named Commands

RPC stands for remote procedure call. Instead of resources, the API exposes actions: calculateTax, orders.cancel, refundPayment. JSON-RPC is a common concrete form, wrapping the method name and parameters in a small JSON envelope. RPC fits command-heavy domains where inventing a fake resource just to avoid a verb would be dishonest.

SOAP: XML Envelopes And Strict Contracts

SOAP wraps every request and response in an XML envelope and describes the whole service in a machine-readable WSDL contract. It predates REST's popularity and remains common in finance, government, travel, and other enterprise systems. It is verbose, but its strict schemas and formal contracts are exactly why regulated industries kept it.

GraphQL: One Endpoint, Client-Selected Data

GraphQL exposes a typed schema at a single endpoint, and each client asks for exactly the fields it needs, across related objects, in one query. Where a REST client might call /customers/42 and then /customers/42/orders, a GraphQL client fetches both shapes in one request. It is a query language with its own syntax, not JSON and not JavaScript.

gRPC: Generated Clients For Internal Services

gRPC defines services and messages in Protocol Buffer files and generates typed client and server code from them. Instead of building URLs, a client calls a generated method such as UserService.GetUser. Its efficient binary encoding and streaming support make it common between internal backend services, where both sides are controlled and browser readability does not matter.

Webhooks: The API Calls You

Everything above is the client pulling data. A webhook reverses the direction: you register a URL, and the provider's system sends an HTTP request to you when something happens, such as a payment succeeding. Webhooks are not a competing request style; they are a delivery pattern that pairs with the styles above so clients do not have to poll for changes.

Persistent Connections: WebSockets And Server-Sent Events

Some integrations need a stream rather than a request. WebSockets hold open a two-way connection for chat, live dashboards, or games. Server-sent events hold open a one-way stream from server to client. GraphQL subscriptions and gRPC streaming build on the same idea: the connection outlives a single request so updates can flow as they happen.

Recognizing What You Are Integrating With

When a provider hands you API documentation, identify the style first, because it decides everything downstream: how requests are shaped, how errors arrive, what tooling exists, and what client code you will write. A WSDL file means SOAP. A single /graphql endpoint means GraphQL. .proto files mean gRPC. Resource paths with HTTP methods mean REST. "Register a callback URL" means webhooks.

This track teaches the plumbing every style shares first: HTTP requests, status codes, headers, JSON, timeouts, retries, and authentication. The REST, RPC, GraphQL, and gRPC orientation, SOAP and XML APIs, and Webhooks lessons then go deep on each style.

What To Check

Before moving on, make sure you can:

  • explain why an API is an agreement rather than a technology
  • explain why APIs are platform-independent and language-agnostic
  • state what REST stands for and why statelessness and resource paths matter
  • distinguish RPC commands from REST resources
  • say where SOAP is still common and why
  • describe GraphQL's single endpoint and field selection in one sentence
  • say when gRPC's generated clients are worth it
  • explain how webhooks reverse the request direction
  • name the persistent-connection options for streaming data

What You Should Be Able To Do

After this lesson, you should be able to look at any API's documentation and identify which style it uses, explain the trade-off that style makes, and know which later lesson in this track covers it in depth.

Practice

Practice: Identify The API Style

You receive documentation snippets from five providers. Write a PHP function that maps each snippet's key signal to the API style it indicates.

Requirements

  • Accept a short description of the documentation signal.
  • Recognize a WSDL contract as SOAP.
  • Recognize a single /graphql endpoint as GraphQL.
  • Recognize .proto service definitions as gRPC.
  • Recognize resource paths with HTTP methods as REST.
  • Recognize "register a callback URL" as webhooks.
  • Return the style plus one sentence on what integrating with it will involve.
Show solution
PHP example
<?php

declare(strict_types=1);

function identifyApiStyle(string $signal): array
{
    $signal = strtolower($signal);

    if (str_contains($signal, 'wsdl')) {
        return ['style' => 'SOAP', 'work' => 'Parse XML envelopes against a strict WSDL contract.'];
    }

    if (str_contains($signal, '/graphql')) {
        return ['style' => 'GraphQL', 'work' => 'Write queries selecting exact fields and handle errors inside 200 responses.'];
    }

    if (str_contains($signal, '.proto')) {
        return ['style' => 'gRPC', 'work' => 'Generate a typed client from the proto files and send deadlines.'];
    }

    if (str_contains($signal, 'callback url')) {
        return ['style' => 'Webhooks', 'work' => 'Expose an endpoint, verify signatures, and handle retries idempotently.'];
    }

    return ['style' => 'REST', 'work' => 'Call resource paths with HTTP methods and handle status codes.'];
}

$signals = [
    'A WSDL file describing operations',
    'One POST /graphql endpoint with a schema explorer',
    'Download the .proto service definitions',
    'Register a callback URL for payment events',
    'GET /v1/invoices/{id} with standard methods',
];

foreach ($signals as $signal) {
    $result = identifyApiStyle($signal);
    echo $result['style'] . ': ' . $result['work'] . PHP_EOL;
}

// Prints:
// SOAP: Parse XML envelopes against a strict WSDL contract.
// GraphQL: Write queries selecting exact fields and handle errors inside 200 responses.
// gRPC: Generate a typed client from the proto files and send deadlines.
// Webhooks: Expose an endpoint, verify signatures, and handle retries idempotently.
// REST: Call resource paths with HTTP methods and handle status codes.

Real documentation mixes signals, and some providers offer several styles at once. The first style you confirm decides which lesson in this track to reread before integrating.