Dex: Created page with "HTTP endpoints are the public “doors” into a system. How those doors are described, exposed, and discovered determines whether an API is usable, evolvable, and maintainable. This article explains what HTTP endpoints really are, how clients discover them, and why good discovery design matters more than most people realise. == Context == HTTP was not originally designed for APIs — it was designed for '''documents linked together'''. APIs inherited HTTP, and with i..."

2026-03-13T19:04:08Z

Created page with "HTTP endpoints are the public “doors” into a system. How those doors are described, exposed, and discovered determines whether an API is usable, evolvable, and maintainable. This article explains what HTTP endpoints really are, how clients discover them, and why good discovery design matters more than most people realise. == Context == HTTP was not originally designed for APIs — it was designed for '''documents linked together'''. APIs inherited HTTP, and with i..."

New page

HTTP endpoints are the public “doors” into a system. How those doors are described, exposed, and discovered determines whether an API is usable, evolvable, and maintainable. This article explains what HTTP endpoints really are, how clients discover them, and why good discovery design matters more than most people realise.

== Context ==
HTTP was not originally designed for APIs — it was designed for '''documents linked together'''.
APIs inherited HTTP, and with it came both power and expectations.

In practice, many systems still treat endpoints as:
* Hard‑coded URLs
* Private knowledge
* Tribal information passed between developers

This works at small scale, but fails as soon as:
* Clients multiply
* Versions evolve
* Integrations become external
* Automation replaces humans

Endpoint discovery is the difference between:
* “You must read the docs first”
* and “The system explains itself”

== What Is an HTTP Endpoint? ==
At its simplest, an HTTP endpoint is:

* A URI
* That accepts HTTP requests
* And returns HTTP responses

But that definition is incomplete.

An endpoint is not just:
<code>/api/users/123</code>

It is the combination of:
* Address (URI)
* Method (GET, POST, PUT, DELETE, etc.)
* Representation (JSON, XML, HTML, etc.)
* Behaviour
* Constraints
* Links to other behaviour

In other words:
'''An endpoint is a capability, not a string.'''

== Endpoints as Capabilities ==
A useful mental model is to treat each endpoint as a capability boundary.

For example:
* “Fetch a user”
* “Create a job”
* “Submit an application”
* “Discover available actions”

Clients should care about:
* What they can do
* What data they can exchange
* What happens next

They should not care about:
* Folder‑like URL structures
* Internal routing logic
* Implementation details

This is where discovery becomes critical.

== Why Discovery Exists ==
Discovery answers a simple question:

'''“How does a client know what it can do next?”'''

Without discovery:
* Clients must be pre‑programmed
* URLs become contracts
* Change becomes dangerous

With discovery:
* Clients can adapt
* Systems can evolve
* Capabilities can be added safely

Discovery turns an API from:
* A static interface
into
* A navigable system

== Levels of Endpoint Discovery ==
Discovery is not all‑or‑nothing. There are layers.

=== 1. Out‑of‑Band Discovery ===
This is the most common approach.

Examples:
* README files
* Wiki pages
* Swagger UI
* Human documentation

Characteristics:
* Humans read first
* Clients are manually coded
* Automation depends on discipline

This is acceptable — but fragile.

=== 2. Entry‑Point Discovery ===
The system exposes a known starting point.

Example:
<code>/api</code>
<code>/</code>
<code>/.well-known/</code>

From this entry point, the system returns:
* Available resources
* Links to capabilities
* Version information

This is where HTTP starts to behave like a system, not just a transport.

=== 3. Link‑Driven Discovery ===
Responses include links to related actions.

For example:
* A job includes a link to apply
* An application includes a link to upload documents
* A result includes a link to its status

This is often referred to as:
* HATEOAS (Hypermedia As The Engine Of Application State)

In practical terms:
'''The response tells the client what is possible next.'''

=== 4. Machine‑Readable Capability Descriptions ===
The system provides formal descriptions such as:
* OpenAPI
* WADL
* JSON Schema
* ALPS
* Link relation metadata

These allow:
* Tooling
* Validation
* Client generation
* Inspection
* Automation

They do not replace runtime discovery — they complement it.

== Describing Endpoints Properly ==
A well‑described endpoint answers:

* What does this do?
* What input does it accept?
* What output does it return?
* What errors can occur?
* What links does it expose?
* What state does it represent?

Poor descriptions focus on:
* URL patterns
* Parameter lists
* Code samples only

Good descriptions focus on:
* Behaviour
* Meaning
* Transitions

== HTTP Itself Is a Discovery Mechanism ==
HTTP already provides discovery tools — they are just underused.

=== OPTIONS ===
The <code>OPTIONS</code> method allows a client to ask:
* “What is allowed here?”

This can expose:
* Supported methods
* Accepted content types
* Authentication requirements

=== Content Negotiation ===
Through headers like:
* <code>Accept</code>
* <code>Content-Type</code>

Clients and servers discover:
* Available representations
* Versioning strategies
* Backwards compatibility paths

=== Status Codes ===
Status codes are not errors — they are signals.

* 200 tells you success
* 401 tells you authentication is required
* 403 tells you the capability exists but is denied
* 404 tells you nothing exists here
* 409 tells you state matters

Each one communicates system behaviour.

== Well‑Known URIs ==
The <code>/.well-known/</code> namespace exists specifically for discovery.

Examples:
* OpenID configuration
* Service metadata
* Capability manifests

Using well‑known locations avoids:
* Guesswork
* Hard‑coding
* Documentation drift

It also signals architectural maturity.

== Discovery vs Versioning ==
One of the strongest arguments for discovery is version resilience.

If clients:
* Follow links
* Honour media types
* React to capabilities

Then:
* URLs can change
* Versions can coexist
* Features can be introduced gradually

Versioning becomes a property of behaviour, not path names.

== Common Pitfalls ==
* Treating URLs as permanent contracts
* Encoding behaviour into paths
* Returning data without links
* Relying entirely on external documentation
* Generating OpenAPI but not aligning runtime behaviour
* Confusing routing structure with API design

Most API “breakages” are discovery failures.

== Design & Architecture Considerations ==
When designing endpoint discovery:

* Start from an entry point
* Think in capabilities, not controllers
* Make transitions explicit
* Use links generously
* Keep descriptions close to the runtime system
* Allow clients to ask questions

Discovery is not overhead — it is operational safety.

== Troubleshooting & Diagnostics ==
When clients struggle:

* Inspect the first response — is there an entry point?
* Check for missing links
* Look for hard‑coded assumptions
* Verify content negotiation
* Test OPTIONS responses
* Compare documentation to live behaviour

Most issues appear immediately once discovery is examined.

== Related Topics ==
* [[REST and Hypermedia]]
* [[OpenAPI and WADL]]
* [[Designing Evolvable APIs]]
* [[Progressive Enhancement in APIs]]

== References ==
* HTTP/1.1 and HTTP/2 specifications
* REST architectural style
* OpenAPI Specification
* WADL
* RFC 5785 (Well‑Known URIs)

Describing HTTP Endpoints and Discovery - Revision history