API Path

Overview

API Path is the portion of an API URL that identifies a resource or operation relative to the base URL. It is used to route a request to the intended capability and encode hierarchical resource relationships. It differs from a query parameter, which modifies or filters a request without selecting the primary route.

A typical implementation works as follows: The client joins the documented path with the base URL, substitutes encoded path parameters, selects an HTTP method, and sends the request. The API Path owner should publish stable error semantics and guidance on whether correction, retry, status lookup, or escalation is appropriate.

Common risks include incorrect encoding and ambiguous trailing slashes. Important failure modes include incorrect encoding, ambiguous trailing slashes, path traversal, conflicting routes, and placing sensitive values in paths. These failures can cause errors or disclosure.

Core controls require teams to define consistent naming, validate and encode parameters, avoid secrets, document case rules, version deliberately, and test routing conflicts. Observability for API Path should record operation, version, principal, request ID, latency, retry count, error code, and final state without exposing secrets.

Operational evidence should include base URL, path template, concrete path, method, route name, parameter values, and API version. API Path should be documented alongside API Base URL, API Gateway, and API Version. For API Path, the application should preserve a correlation path from request construction through response, asynchronous completion, and final business state.

Testing API Path should cover malformed input, denied access, rate limits, timeouts, duplicates, asynchronous completion, and version changes.