Redirects

The “redirect” is a fundamental part of the HTTP protocol. The concept waspresent and is documented already in the first spec (RFC 1945), published in1996, and it has remained well-used ever since.

A redirect is exactly what it sounds like. It is the server sending back aninstruction to the client instead of giving back the contents the clientwanted. The server says “go look overhere instead for that thing you askedfor“.

Redirects are not all alike. How permanent is the redirect? What requestmethod should the client use in the next request?

All redirects also need to send back aLocation: header with the new URI toask for, which can be absolute or relative.

Permanent and temporary

Is the redirect meant to last or just remain valid for now? If you want a GETto permanently redirect users to resource B with another GET, send backa 301. It also means that the user-agent (browser) is meant to cache this andkeep going to the new URI from now on when the original URI is requested.

The temporary alternative is 302. Right now the server wants the client tosend a GET request to B, but it should not cache this but keep trying theoriginal URI when directed to it next time.

Note that both 301 and 302 make browsers do a GET in the next request, whichpossibly means changing the method if it started with a POST (and only ifPOST). This changing of the HTTP method to GET for 301 and 302 responses issaid to be “for historical reasons”, but that’s still what browsers do so mostof the public web behaves this way.

In practice, the 303 code is similar to 302. It is not be cached and it makesthe client issue a GET in the next request. The differences between a 302 and303 are subtle, but 303 seems to be more designed for an “indirect response”to the original request rather than just a redirect.

These three codes were the only redirect codes in the HTTP/1.0 spec.

curl however, does not remember or cache any redirects at all so to it,there is really no difference between permanent and temporary redirects.

Tell curl to follow redirects

In curl's tradition of only doing the basics unless you tell it differently,it does not follow HTTP redirects by default. Use the-L, --location optionto tell it to do that.

When following redirects is enabled, curl follows up to 30 redirects bydefault. There is a maximum limit mostly to avoid the risk of getting caughtin endless loops. If 30 is not sufficient for you, you can change the maximumnumber of redirects to follow with the--max-redirs option.

GET or POST?

All three of these response codes, 301 and 302/303, assume that the clientsends a GET to get the new URI, even if the client might have sent a POST inthe first request. This is important, at least if you do something that doesnot use GET.

If the server instead wants to redirect the client to a new URI and wants itto send the same method in the second request as it did in the first, like ifit first sent POST it’d like it to send POST again in the next request, theserver would use different response codes.

To tell the client “the URI you sent a POST to, is permanently redirected to Bwhere you should instead send your POST now and in the future”, the serverresponds with a 308. To complicate matters, the 308 code is only recentlydefined (thespec waspublished in June 2014) so older clients may not treat it correctly. If so,then the only response code left for you is…

The (older) response code to tell a client to send a POST also in the nextrequest but temporarily is 307. This redirect is not be cached by the clientthough, so it’ll again post to A if requested to again. The 307 code wasintroduced in HTTP/1.1.

Oh, and redirects work the same way in HTTP/2 as they do in HTTP/1.1.

Decide what method to use in redirects

It turns out that there are web services out there in the world that want aPOST sent to the original URL, but are responding with HTTP redirects that usea 301, 302 or 303 response codes andstill want the HTTP client to send thenext request as a POST. As explained above, browsers won’t do that and neitherdoes curl by default.

Since these setups exist, and they’re actually not terribly rare, curl offersoptions to alter its behavior.

You can tell curl to not change the non-GET request method to GET after a 30xresponse by using the dedicated options for that:--post301,--post302 and--post303. If you are instead writing a libcurl based application, youcontrol that behavior with theCURLOPT_POSTREDIR option.

Redirecting to other hostnames

When you use curl you may provide credentials like username and password fora particular site, but since an HTTP redirect might move away to a differenthost curl limits what it sends away to other hosts than the original withinthe same transfer.

If you want the credentials to also get sent to the following hostnames eventhough they are not the same as the original—presumably because you trust themand know that there is no harm in doing that—you can tell curl that it is fineto do so by using the--location-trusted option.

Non-HTTP redirects

Browsers support more ways to do redirects that sometimes make lifecomplicated to a curl user as these methods are not supported or recognized bycurl.

HTML redirects

If the above was not enough, the web world also provides a method to redirectbrowsers by plain HTML. See the example<meta> tag below. This is somewhatcomplicated with curl since curl never parses HTML and thus has no knowledgeof these kinds of redirects.

<meta http-equiv="refresh" content="0; url=http://example.com/">

JavaScript redirects

The modern web is full of JavaScript and as you know, JavaScript is a languageand a full runtime that allows code to execute in the browser when visitingwebsites.

JavaScript also provides means for it to instruct the browser to move on toanother site - a redirect, if you will.