REST APIs: custom HTTP headers vs URL parameters

Use HTTP Headers for sending,

• Directives ( read the input in JSON format )

• Metadata ( who is making the request )

• Common data to be sent on every request ( like Authentication, session )

Use Path Parameters to make,

• Specific requests on a resource ( /country/state/city )

  They must form a logical hierarchy

Use Query Parameters for sending,

• Action requests on a resource ( like pagination, filters )

The URL indicates the resource itself. A "client" is a resource that can be acted upon, so should be part of the base url: /orders/view/client/23.

Parameters are just that, to parameterize access to the resource. This especially comes into play with posts and searches: /orders/find?q=blahblah&sort=foo. There's a fine line between parameters and sub-resources: /orders/view/client/23/active versus /orders/view/client/23?show=active. I recommend the sub-resource style and reserve parameters for searches.

Since each endpoint REpresents a State Transfer (to mangle the mnemonic), custom headers should only be used for things that don't involve the name of the resource (the url), the state of the resource (the body), or parameters directly affecting the resource (parameters). That leaves true metadata about the request for custom headers.

HTTP has a very wide selection of headers that cover most everything you'll need. Where I've seen custom headers come up is in a system to system request operating on behalf of a user. The proxy system will validate the user and add "X-User: userid" to the headers and use the system credentials to hit the endpoint. The receiving system validates that the system credentials are authorized to act on behalf of the user, then validate that the user is authorized to perform the action.