OPTIONS requests

OPTIONS requests are made in one of two ways:

• deliberately by the client as a form of resource discovery
• automatically behind the scenes—the so-called "preflight" OPTIONS request

Resource discovery

RESTful can provide "discovery" data about each resource, such as an array of metadata for each of the public fields that the resource has defined. It does this through the OPTIONS call.

A sample OPTIONS request to the restful_example.module's articles resource

jQuery.ajax({
    url: "http://drupalserver.com/api/v1.0/articles",
    type: "OPTIONS",
})

The response will contain an array for each resource item that is available to this user. You could think of the OPTIONS request as a way to see the schema info of whatever data a GET request would return.

Also, bear in mind that every particular instance of an entity returned in the OPTIONS response could have individual data added through custom discovery sections.

For the curious: Preflight OPTIONS requests with CORS

A blog post by Remy Sharp explains preflight this way:

preflight is an additional request the XHR object makes to make sure it's allowed to actually make the request.

If you're accessing your RESTful API from a different domain (i.e. you're using CORS) and you study your browser's network requests, you'll notice that every request comes with an initial "preflight" OPTIONS request. RESTful handles this for you, and under normal circumstances you need not be concerned, other than out of curiosity.

A warning regarding CORS and authenticated resources

RESTful 2.x currently returns a 401 (unauthorised) on OPTIONS requests to authenticated resources, if the OPTIONS request does not provide authentication. Preflight OPTIONS requests (which are generated by the browser) will not contain auth, as per the W3 spec for CORS preflight requests, and thus will fail with a 401.

This is a known issue with RESTful 2.x. The best workaround currently suggested is to avoid CORS altogether, by using xdomain.

There's an issue at https://github.com/RESTful-Drupal/restful/issues/844 with further details.