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?

score 31 · Accepted Answer · edited May 23 '17 at 11:48

31

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.

edited May 23 '17 at 11:48

Community

1
1

answered Jul 11 '16 at 01:55

Paul Samsotha

205,037
37
486
720

Thanks, is WADL seems like a standard, am I supposed to provide WADL if I'm developing REST compliant services for my clients? – user2727195 Jul 11 '16 at 02:00
You don't _have_ to. It doesn't hurt having it though. – Paul Samsotha Jul 11 '16 at 02:01
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 – user2727195 Jul 11 '16 at 02:03
1

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 – Paul Samsotha Jul 11 '16 at 02:26
1

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. – Paul Samsotha Jul 11 '16 at 02:27
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. – user2727195 Jul 11 '16 at 02:29
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... – Paul Samsotha Jul 11 '16 at 02:34
... the request will simply skip the resource, and go straight to the response filter, where the CORS response headers are added to the response. – Paul Samsotha Jul 11 '16 at 02:34
1

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. – Paul Samsotha Jul 11 '16 at 02:36

OPTIONS call for meta before REST API call

1 Answers1

Linked