Pragmatic Geographer


Access vs. Validity in Pragmatic HTTP APIs

It is obviously important to define the difference between the access a current client has to a resource and all of the valid methods that any client could potentially have.

This is the difference between the capabilities of a particular client (access) vs. the capabilities of the server (validity). Missing just one has significant problems:

Missing Access: Clients have to test every possible action to determine what they are actually allowed to do.

Missing Validity: The client knows what they can do, but not what the server can do. Should they need to look around to find a mechanism to be granted permission to act as they need?

And indeed, there appears to be a perfectly good HTTP header that means to address at least one of these:


The Allow entity-header field lists the set of methods supported by the resource identified by the Request-URI. The purpose of this field is strictly to inform the recipient of valid methods associated with the resource.

That appears to cover validity. But is there some other standard means of defining permitted actions? Must a user try and fail with HTTP 403 Forbidden (rather than HTTP 405 Method Not Allowed)?

I’ve come across three potential solutions.

  1. Pragmatism.

    If there isn’t any granting mechanism or such, just use the Allow header to capture access. Without having to make addition requests, a client immediately knows what actions it can take next.

  2. The OPTIONS method

    The what?

    The OPTIONS method…allows the client to determine the options and/or requirements associated with a resource, or the capabilities of a server, without implying a resource action or initiating a resource retrieval.

    Seemingly few servers implement this method and it is a damn shame, because it could largely eliminate verbose API documentation and vastly increase programability of a resource.

    You could define not just the permitted methods for that specific client, but also better define how to interact with the resource and describe how to potentially be granted additional access rights.

    Shout out to Django Rest Framework for including this out-of-the-box.

  3. Add an additional header

    Something like a Permitted header might make sense, but like all extra headers there are concerns – they are less easily discovered by clients, hostile intermediaries may drop them, or they might be superseded by modifications to the HTTP spec itself.