As a frontend developer, have you ever found yourself repeatedly debugging an unfamiliar API: Does this endpoint support POST? Should I send JSON or form data? In fact, HTTP has long included a built-in ‘API documentation’—`OPTIONS` method, which can dynamically inform you ‘what can be done at this endpoint’. Today, we will delve into this often-overlooked practical tool to double the efficiency of API integration.

1. OPTIONS Beyond CORS Endpoint Discovery

When mentioning the OPTIONS method, most people’s first reaction is ‘CORS preflight request’. However, few know that its core design intention ispassive interface capability discovery—allowing the client to know exactly what operations are supported by the target endpoint without attempting to call it.

All mainstream HTTP clients natively support OPTIONS requests. For example, you can easily initiate one using the browser’s fetch():

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

After initiating the request, the server will return a concise response. A basic OPTIONS response looks like this:

HTTP/1.1 204 No Content
Date: Mon, 23 Sep 2024 02:57:38 GMT
Server: KKachel/1.2
Allow: GET, PUT, POST, DELETE, OPTIONS

The most critical part is the Allow header, which directly lists all HTTP methods supported by the endpoint. Even better, mainstream web frameworks like Express and Koa automatically generate this list based on route configurations, requiring almost no additional coding from developers.

Want to quickly verify if your server supports it? Execute this curl command in the terminal (replace with your endpoint address):

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

Allow header also has a practical trick: it can dynamically return based on permissions. For example, only including DELETE and PUT in the Allow header when the user has resource write permissions, achieving basic permission visualization.

2. Core Response Headers: Unlocking Interface Details

In addition to the Allow header, the OPTIONS response also includes several standardized headers that can accurately convey key information about the interface’s format, encoding, and more.

1. Data Format and Compression: Accept and Accept-Encoding

You may often use Accept (to tell the server what format of data you want) and Accept-Encoding (to tell the server what compression methods you support) in request headers, but they are equally important in the OPTIONS response—this time, the server actively informs the client ‘what I can provide’.

Look at this example response:

HTTP/1.1 204 No Content
Date: Mon, 23 Sep 2024 02:57:38 GMT
Server: KKachel/1.2
Allow: GET, PUT, POST, DELETE, OPTIONS
Accept: application/vnd.my-company-api+json, application/json, text/html
Accept-Encoding: gzip,brotli,identity

Accept Response Header: Clearly specifies the MIME types supported by the endpoint. For example, in the above configuration, the interface supports both a custom format application/vnd.my-company-api+json and standard JSON and HTML. Frontend developers can leverage this: by adding text/html support to JSON API endpoints, they can directly view the debugging page by opening the interface URL in a browser, facilitating team sharing and debugging.
Accept-Encoding Response Header: Informs the client of the available request body compression methods. gzip and brotli are common efficient compression algorithms, while identity indicates no compression. When making requests, compressing data according to this configuration can significantly reduce transmission size.

2. Method-Specific Formats: Accept-Patch/Post/Query

For the three frequently used methods PATCH, POST, and QUERY, HTTP provides dedicated response headers that precisely specify the request body formats supported by each method—its values directly correspond to the valid values of the Content-Type header during requests.

Example:

HTTP/1.1 204 No Content
Date: Mon, 23 Sep 2024 02:57:38 GMT
Server: KKachel/1.2
Allow: OPTIONS, QUERY, POST, PATCH
Accept-Patch: application/json-patch+json, application/merge-patch+json
Accept-Query: application/graphql
Accept-Post: multipart/form-data, application/vnd.custom.rpc+json

The purpose of each header is clear:

Accept-Patch: The formats supported by PATCH requests. The above configuration indicates that the interface accepts two standard patch formats: ‘JSON Patch’ and ‘JSON Merge Patch’, allowing the frontend to choose the implementation method for partial updates as needed.
Accept-Query: The formats supported by the QUERY method. Here it is specified as application/graphql, indicating that this endpoint can directly receive GraphQL query statements.
Accept-Post: The formats supported by POST requests. The example supports both multipart/form-data (for file uploads) and a custom JSON-RPC format, so the frontend does not need to guess how to upload or submit data.

3. Special Notes: PUT and DELETE

Careful developers may notice: there is no dedicated format header for the PUT method (like Accept-Put). This is because in the HTTP specification, GET and PUT are designed as ‘symmetric operations’, and theoretically, the formats supported by PUT can be inferred indirectly through the Accept header, but the specification does not explicitly state this.

As for the DELETE method, it is simpler: the HTTP standard stipulates that DELETE requests should not contain a request body, so it is sufficient to determine whether the delete operation is supported through the Allow header without additional format specifications.

3. Advanced Usage: From Document Links to Full Server Discovery

OPTIONS capabilities extend beyond method and format descriptions; it can also play important roles in documentation guidance and protocol extensions.

1. Embedding Document Links: The ‘Manual’ of the Interface

OPTIONS responses are the best carrier for linking interfaces to documentation. You can include a Link header in the response, pointing to machine-readable OpenAPI definitions and human-readable documentation pages, or even add friendly tips in the response body.

Example response:

HTTP/1.1 200 OK
Date: Mon, 23 Sep 2024 04:45:38 GMT
Allow: GET, QUERY, OPTIONS
Link: &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/plain

Hey there!
Thanks for checking out this API. You can find the docs for this
specific endpoint at: https://docs.example.org/api/some-endpoint
Cheers,
The dev team

Here, rel="service-doc" indicates human-readable documentation, while rel="service-desc" indicates machine-readable service descriptions (like OpenAPI). These are IANA standardized link relation types, ensuring compatibility. It is recommended to keep the response body concise, with core information directed to independent documentation pages via links.

2. Protocol Extension Support: Practices in WebDAV

In extended protocols like WebDAV (HTTP-based file management protocol) and CalDAV (calendar synchronization), OPTIONS serves as a standard capability discovery tool. For example, a WebDAV server’s OPTIONS response:

HTTP/1.1 204 No Content
Date: Mon, 23 Sep 2024 05:01:50 GMT
Allow: GET, PROPFIND, ACL, PROPPATCH, MKCOL, LOCK, UNLOCK
DAV: 1, 2, 3, access-control, addressbook, calendar-access

Through the DAV header, clients can immediately know the WebDAV versions and extended features supported by the server (such as address book and calendar access), which is particularly useful for frontend developers developing cloud storage and calendar synchronization tools.

3. Full Server Capability Discovery: Asterisk Requests

Typically, HTTP requests target specific paths on the server (like GET /path HTTP/1.1), but OPTIONS supports a special ‘full server discovery’—using an asterisk to replace the path:

OPTIONS * HTTP/1.1

Here, the asterisk does not represent a URI path but indicates ‘querying the capabilities of the entire server’. However, it is important to note that many clients (including the browser’s fetch()) do not support this request format, but classic servers like Apache and Nginx can respond to it.

If you want to try it, execute the following command with curl:

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

4. Frontend Practice Recommendations: Making OPTIONS a Development Tool

Check OPTIONS when integrating new APIs: When encountering an unfamiliar interface, the first step is to initiate an OPTIONS request to quickly grasp the supported methods, formats, and documentation locations, avoiding blind debugging.
Enhance experience with OpenAPI: If the backend also provides OpenAPI documentation, you can point to the documentation address through the OPTIONS Link header, allowing frontend tools (like Swagger UI) to automatically load the documentation.
Handle dynamic feedback on permissions: By dynamically changing the Allow header, the frontend can update UI interactions in real-time (e.g., hiding the delete button if there are no delete permissions), enhancing user experience.
Avoid custom solutions: Do not design interfaces like ‘/api/meta’ to return capability information; OPTIONS is the HTTP standard solution, offering better compatibility and readability.

HTTP OPTIONS solves the core issue of ‘what can the interface do’ in a standardized way. For frontend developers, effectively utilizing OPTIONS can significantly reduce the trial-and-error cost when integrating APIs, making interface interactions more efficient and standardized. Next time you encounter an unfamiliar interface, consider asking: ‘Does your OPTIONS response have the answer?’

Follow our public account ⬇️

If you like it, please help by liking and sharing Frontend Development Tips: Exploring API Capabilities with HTTP OPTIONS Thank you 🙏