OPTIONS call for meta before REST API call

Question

I'm trying to understand how this system is working under the hood. The system is REST based which is pretty standard, what I don't get the client makes a OPTIONS call before each API call and XML content is returned in the format. It's using Jersey Java.

OPTIONS response for the DELETE method

Access-Control-Request-Method: DELETE is passed in the headers

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<application xmlns="http://wadl.dev.java.net/2009/02">
    <doc xmlns:jersey="http://jersey.java.net/" jersey:generatedBy="Jersey: 2.8 2014-04-29 01:25:26"/>
    <grammars/>
    <resources base=“http://example.com”>
        <resource path=“data/gasdfasdg/entity”>
            <method id="deleteEntity" name="DELETE">
                <request>
                    <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string"/>
                </request>
                <response>
                    <representation mediaType="application/json"/>
                </response>
            </method>
            <method id="getOneEntitysMetadata" name="GET">
                <request>
                    <param xmlns:xs="http://www.w3.org/2001/XMLSchema" name="q" style="query" type="xs:string"/>
                    <param xmlns:xs="http://www.w3.org/2001/XMLSchema" name="x-dps-compute-content-size" style="header" type="xs:boolean"/>
                    <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string"/>
                </request>
                <response>
                    <representation mediaType="application/json"/>
                </response>
            </method>
            <method id="createOrUpdateEntity" name="PUT">
                <request>
                    <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string"/>
                </request>
                <response>
                    <representation mediaType="application/json"/>
                </response>
            </method>
        </resource>
    </resources>
</application>

Questions:

A. Is it a standard or industry practice for client to call OPTIONS first, process, and analyze the response and determine the API, parameters etc. before making an actual call? Earlier I've been just looking at docs and programming my REST calls in client (JavaScript) accordingly.

B. Is this call made by browser automatically (preflight) or was it programmed in the client?

Rianna

Answer 1

To understand what's going on, you need to understand about CORS (cross origin resource sharing). The OPTIONS request , is the pre-flight request (made by the browser, in response to the client trying to make a cross origin ajax request), which is an initial request to the server to check if that client is allowed to make a request to the server. The pre-flight request sends particular headers that the server understands, and the server will response back with different headers. For instance, the client might send

Origin: http://foo.example
Access-Control-Request-Method: DELETE

With these two request headers, there are two corresponding response headers that the browser expects. The request headers are basically asking "is this origin allowed" and "is this method allowed". The servers should respond with

Access-Control-Allow-Origin: http://foo.example
Access-Control-Allow-Methods: POST, GET, OPTIONS, DELETE

The above are the response headers, saying that the origin is allowed, and that those methods are allowed. If you are not seeing those headers, that means that you do not have CORS configured on your server. If the browser does not see those response headers, it will not make the actual request. To configure CORS, generally a simple filter is used. Some containers, like Tomcat and Jetty, have a simple filter implementation you can configure, or you can just whip up your own, for example.

Note the above scenario is usually only for browsers and XmlHTTPRequest requests, as mentioned in the above link.

What the XML is, is that WADL. The only reason you are getting this, is because Jersey has it's own WADL feature enabled by default. WADL is not something that is mandatory, but Jersey has it, and it's configured to respond to OPTIONS requests. If you disabled the WADL (which is possible), instead of getting the XML, you would just get a 405 Not Allowed response, meaning the OPTIONS method is not allowed for that endpoint. The WADL is nothing that is standard is regards to the CORS protocol. It's just a side effect of Jersey's WADL feature. WADL and CORS have nothing to do with each other.

Heres

Thanks, is WADL seems like a standard, am I supposed to provide WADL if I'm developing REST compliant services for my clients? – Rianna

You don't have to. It doesn't hurt having it though. – Heres

ok, the page says "consortium has no current plans to standardize it", for me REST methods and URI path are enough to tell what's intended, and what goes in the body maybe specified through schemas – Rianna

One thing to note about the Jersey CORS filter I linked to, is that it is not a great implementation. It is not even a correct implementation (I will have to update the answer one of these days :-). For the CORS protocol, the pre-flight response should be a 200 status, without returning a body. A better implementation of the filter would be to use a request filter and a response filter together. The request filter will check if it is an OPTIONS request with an Origin header. If it is then abort the request with a 200 status. The response filter will still get called adding the headers – Heres

With this implementation, the WADL will never get sent. Which is what should happen. It's a waste of bandwidth to send the XML for a pre-flight request. – Heres

I didn't get you on A better implementation of the filter would be to use a request filter and a response filter together, please explain more. – Rianna

In the request filter, check for an OPTIONS method, and check for the ORIGIN header. If these two are present, then it is a CORS pre-flight request. This means that the resource should not get hit. In the current implementation, using only the response fitler, the resource is hit (which is the Jersey WADL resource). But if we abort the request (from within the request filter), then the resource never gets hit. But for all responses, aborted or not, the response filter is always called. So if you simply abort with a 200 in the request filter, when the pre-flight check is met, then... – Heres

... the request will simply skip the resource, and go straight to the response filter, where the CORS response headers are added to the response. – Heres

In the request filter (ContainerRequesFilter), you can do requestContext.abortWith(Response.ok().build()). This will abort the request, but the response filter will still get called, adding the response headers. – Heres