Describing HTTP Endpoints and Discovery

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: /api/users/123

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: /api / /.well-known/

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 OPTIONS 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:

Accept
Content-Type

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 /.well-known/ 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.

References

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