Expanded HTTP Method Support

HTTP and its secure variant, HTTPS, are the protocols used by every web client to talk to web applications. A key part of the protocol is the HTTP method. Traditionally, web applications used a very limited set of HTTP methods. It is common for application servers, proxies and routers (such as the Heroku HTTP router) to prevent unknown methods from being used. This unnecessary constraint of the Heroku HTTP router has increasingly become a limitation to developers building modern web applications.

In the past, if you tried to use an unsupported HTTP method in your Heroku application, clients would receive a 405 METHOD_NOT_ALLOWED error.

As of today, that's no longer the case. The Heroku routers now accept any HTTP method, allowing you to use newer methods that have recently gained adoption, such as PATCH.

Why is this important?

Many new web frameworks use recently introduced HTTP methods such as PATCH or even custom methods that are not yet standardized. Ruby on Rails is one such framework. Rails has constantly evolved since its birth to always incorporate the latest development techniques. One such evolution is happening in Rails 4 where the framework uses the PATCH HTTP method to perform partial updates of resources.

Before Heroku removed restrictions on HTTP method, it was not possible to leverage this new functionality in Rails 4. Now that any method is supported, you can take full advantage of PATCH support in Rails 4.

Background

For the curious, a little more background is in order.

HTTP is extensible

A huge factor in HTTP's popularity has been its extensibility. HTTP is a simple protocol that can be used for many different purposes. For instance, the HTTP/1.1 Spec defines the following set of methods: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, CONNECT.

But the spec also states that new methods can be added. In fact, a number of other RFCs have standardized additional HTTP methods, often for specific applications such as version control or calendaring. Yet in most cases, regardless of the underlying application, developers can leverage the same supporting infrastructure: load balancers, proxies, caching proxies; all designed for HTTP.

The HTTP `PATCH` Method

A recent extension to HTTP is RFC5789, which introduced the PATCH method. This method is particularly useful for web application developers, as it standardizes a common way to make partial updates to resources. Rails 4 and many other libraries now make use of it.

We can quickly demonstrate how it is used by deploying a basic Sinatra app to Heroku using the quick start guide. Replace the code in app.rb with:

require 'sinatra'
require 'json'

class App < Sinatra::Base

  # fake persistent data.
  DATA = { "a" => 1, "b" => 2, "c" => 3 }

  put '/data' do
    # put replaces the existing resource so we simply return the new resource
    new_data = JSON.parse(request.body.read)
    new_data.to_json
  end

  patch '/data' do
    # patch 'patches' the existing resource
    new_data = DATA.merge(JSON.parse(request.body.read))
    new_data.to_json
  end

end

Once your app is deployed, perform a PATCH and PUT request with curl:

$ curl -X PATCH http://shiny-object-1234.herokuapp.com/data -d '{"a": 2, "b": 3}'
{"a":2,"b":3,"c":3}
$ curl -X PUT http://shiny-object-1234.herokuapp.com/data -d '{"a": 2, "b": 3}'
{"a":2,"b":3}

The PATCH logic merges the new values into the existing data structure and returns the whole data structure, whereas PUT simply replaces the old data structure with a new one. While this example doesn't persist the changes, it demonstrates the semantic difference between these two HTTP methods.

Other HTTP methods

PATCH is just one example of how a new HTTP method was defined, standardized and successfully achieved widespread use. Because Heroku no longer imposes any restrictions on HTTP methods, future extensions will work seamlessly without requiring explicit support. This also means that the Heroku platform can be used as a proving ground for new, non-standardized HTTP methods.

Why restrict HTTP methods in the first place?

The original motivation for application servers, proxies and HTTP routers to restrict HTTP methods was that these intermediaries often performed more functions than just passing through requests. For example, if an intermediary wants to retry a failed request, it needs to understand whether a retry is safe. POST and PATCH requests are generally not safe to retry while GET, PUT, and DELETE are.

Heroku's routers pass requests straight through to the application, without special handling based on the particular HTTP method; the routers therefore handle all requests the same, regardless of which method was used. This results in maximum flexibility for the application developer to use any HTTP method and fully control the semantics of each request.

For more on HTTP routing visit our Dev Center article.

Video Transcript