Essential Reading for IT Development Testers: The Often Overlooked HTTP OPTIONS Method

Assuming you have an API and you want to convey the types of operations that users can perform at a specific endpoint. You can use external description formats like OpenAPI or JSON Schema, but sometimes it’s also nice to convey this information dynamically on the API itself.OPTIONS is the method used for this purpose. You might know this HTTP method from CORS, but its general purpose is to allow clients to passively find out, “What can I do here?”.All HTTP clients typically support sending an OPTIONS request. For example, using fetch():

const response = await fetch(  'https://example.org',  {method: 'OPTIONS'});

A basic OPTIONS response might look like this:

HTTP/1.1 204 No ContentDate: Mon, 23 Sep 2024 02:57:38 GMTServer: KKachel/1.2Allow: GET, PUT, POST, DELETE, OPTIONS

Based on the Allow header, you can quickly understand the available HTTP methods at a specific endpoint. Many web frameworks automatically generate and dynamically create a list of methods by route, so you might get this for free.To check if your server does this, try running the following command (replace with your URL):

curl -X OPTIONS http://localhost:3000/some/endpoint/

One nice thing you can do with the Allow header is that you can also convey access control information at a very basic level. For example, you only include DELETE and PUT if the user has write access to the resource.

Accept and Accept-Encoding

In addition to the HTTP standard headers used for discovery, there are a few others. Here’s an example that showcases several:

HTTP/1.1 204 No ContentDate: Mon, 23 Sep 2024 02:57:38 GMTServer: KKachel/1.2Allow: GET, PUT, POST, DELETE, OPTIONSAccept: application/vnd.my-company-api+json, application/json, text/htmlAccept-Encoding: gzip,brotli,identity

You may already be familiar with Accept and Accept-Encoding in HTTP requests, but they can also appear in responses. The Accept in the response allows you to tell the client the available mimetypes at the endpoint. I like to add text/html to each JSON API endpoint and ensure the API URL can be opened in a browser for easy debugging among developers.

Patching, Posting, and Querying

There are also three other headers you can use: `Accept-Patch`, `Accept-Post`, and `Accept-Query` . These three headers are used to inform the client about the content types available for the `PATCH`, `POST`, and `QUERY` HTTP methods respectively.

For all these headers, their values effectively determine what is valid. The values are for the Content-Type header when making requests.

HTTP/1.1 204 No ContentDate: Mon, 23 Sep 2024 02:57:38 GMTServer: KKachel/1.2Allow: OPTIONS, QUERY, POST, PATCHAccept-Patch: application/json-patch+json, application/merge-patch+jsonAccept-Query: application/graphqlAccept-Post: multipart/form-data, application/vnd.custom.rpc+json

In the above response, the server indicates that it supports both JSON Patch and JSON Merge Patch content types for PATCH requests. It also implies that GraphQL can be used via the QUERY method, and that POST supports standard file uploads and some custom JSON-based formats.

Typically, you won’t find all of these at the same endpoint, but I wanted to provide a few examples together.

Where is PUT?

Strangely, there is no specific header for PUT requests. You could argue that GET and PUT are symmetrical, so perhaps the Accept header kind extends to both. But the specification does not clarify this.

I think the reality is that Accept-Patch is the first header to clearly define this as a feature discovery means regarding OPTIONS. Accept-Post and Accept-Query follow. I believe Accept-Patch is modeled after OPTIONS in the wild, even if HTTP specific does not super clearly define it.

If my explanation here is wrong, I would love to know!

Note: If you want to know about DELETE, DELETE should never have a body, thus, can users need to know that they can delete, which you can see in the Allow header. If this is new, read my other article on GET requests bodies. Most of the information there applies to DELETE as well.

Linking to Documentation

Because the OPTIONS response is also a good place to tell users where to find supplementary documentation. In the example below, I include two machine-readable links to documentation sites, linking to the OpenAPI definition, as well as human-readable information in the response body:

HTTP/1.1 200 OKDate: Mon, 23 Sep 2024 04:45:38 GMTAllow: GET, QUERY, OPTIONSLink: &lt;https://docs.example.org/api/some-endpoint&gt;; rel="service-doc"Link: &lt;https://api.example.org/openapi.yml&gt;; rel="service-desc" type="application/openapi+yaml"Content-Type: text/plainHey there!Thanks for checking out this API. You can find the docs for this specific endpoint at: https://docs.example.org/api/some-endpointCheers,The dev team

I recommend keeping the response minimal and informal; any real information should only exist at its own URL and link to it.

I used service-doc and service-desc link relations here, but you can certainly use any IANA link relation type or customize one. See the Web Linking specification for more information.

Ambiguous Usage

WebDAV Usage

WebDAV, CalDAV, and CardDAV also use OPTIONS for feature discovery. For example:

HTTP/1.1 204 No ContentDate: Mon, 23 Sep 2024 05:01:50 GMTAllow: GET, PROPFIND, ACL, PROPPATCH, MKCOL, LOCK, UNLOCKDAV: 1, 2, 3, access-control, addressbook, calendar-access

Server-Scoped Asterisk Requests

Typically, HTTP requests are sent to a path on the server, the first line looks something like this in HTTP/1.1:

GET /path HTTP/1.1

However, there are some other rarely used “request line” formats. One allows you to discover the available features across the entire server, using an asterisk:

OPTIONS * HTTP/1.1

The asterisk here is not a path. Typically, asterisks are not even allowed in URIs. Many HTTP clients (including fetch()) do not even support this request.

Classic web servers like Apache and Nginx should support this. Give it a try using CURL

curl -vX OPTIONS --request-target '*' http://example.org

Final Remarks

If you have reason to allow clients to discover features at an endpoint, consider using OPTIONS instead of proprietary methods! As you can see in many of these examples, using mimetypes is particularly useful.

If you have questions, other novel uses of OPTIONS, or other ideas around feature discovery, feel free to leave a comment:

Source:

https://evertpot.com/discovering-features-with-http-options/

Accept and Accept-Encoding

Patching, Posting, and Querying

Patching, Posting, and Querying

Where is PUT?

Linking to Documentation

Ambiguous Usage

WebDAV Usage

Server-Scoped Asterisk Requests

Final Remarks

Related posts

Leave a Comment Cancel reply