Skip to content

308 Permanent Redirect

Description

The 308 Permanent Redirect status code indicates that the requested resource has been permanently moved to another URI, and future requests should use the new URI. Unlike the 301 Moved Permanently status code, the 308 Permanent Redirect explicitly preserves the HTTP method used in the original request when following the redirect.

This status code was introduced to address the inconsistent behavior of 301 Moved Permanently across different browsers and clients. Some clients would change a POST request to a GET request when following a 301 redirect, which could lead to unexpected behavior.

The 308 Permanent Redirect ensures that if the original request was a POST, the redirected request will also be a POST, preserving the HTTP method semantics. This is particularly important for forms and API endpoints that rely on specific HTTP methods.

Syntax

The server responds with a 308 Permanent Redirect status and includes the new location:

HTTP/1.1 308 Permanent Redirect
Location: https://example.com/new-path
Content-Type: text/html
Content-Length: [length in bytes]

[Optional response body with a hyperlink to the new location]

Examples

API Endpoint Restructuring Example

A client sends a POST request to an API endpoint that has been permanently moved:

Client Request: 

POST /api/v1/users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Content-Length: 84
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

{
  "name": "Jane Doe",
  "email": "[email protected]",
  "role": "admin"
}

Server Response: 

HTTP/1.1 308 Permanent Redirect
Location: https://api.example.com/api/v2/users
Content-Type: text/plain
Content-Length: 112

This API endpoint has been permanently moved to the v2 API. Your request will be redirected with the same method and body.

The client should resubmit the POST request with the same JSON data to the URL specified in the Location header.

Form Processing Endpoint Change Example

A client submits a form to an endpoint that has been permanently relocated:

Client Request: 

POST /submit-application HTTP/1.1
Host: forms.example.org
Content-Type: application/x-www-form-urlencoded
Content-Length: 156

first_name=Jane&last_name=Smith&email=jane.smith%40example.com&position=Software+Engineer&experience=5&resume_url=https%3A%2F%2Fexample.com%2Fresumes%2Fjsmith.pdf

Server Response: 

HTTP/1.1 308 Permanent Redirect
Location: https://forms.example.org/careers/apply
Content-Type: text/html
Content-Length: 235

<!DOCTYPE html>
<html>
<head>
  <title>Permanent Redirect</title>
</head>
<body>
  <p>Our application submission endpoint has moved permanently. Your browser will automatically resubmit your application to <a href="https://forms.example.org/careers/apply">the new endpoint</a>.</p>
</body>
</html>

Resource Restructuring Example

A client sends a PUT request to update a resource at a URL that has been permanently changed:

Client Request: 

PUT /documents/annual-report/2023 HTTP/1.1
Host: docs.example.com
Content-Type: application/json
Content-Length: 1458
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

{
  "title": "Annual Report 2023",
  "sections": [
    {
      "title": "Financial Summary",
      "content": "..."
    },
    /* More sections */
  ]
}

Server Response: 

HTTP/1.1 308 Permanent Redirect
Location: https://docs.example.com/reports/annual/2023
Content-Type: text/plain
Content-Length: 128

Our document structure has been permanently changed. Your request will be redirected to the new URL with the same method and content.

Summary

The 308 Permanent Redirect status code is an important tool for preserving HTTP method semantics during permanent redirects. It ensures that clients maintain the original request method when following the redirect, which is crucial for proper functioning of web applications and APIs that rely on specific HTTP methods. This status code is particularly valuable when restructuring APIs, changing form processing endpoints, or reorganizing resources in a way that requires maintaining the original HTTP method. Unlike the 301 Moved Permanently status, the 308 Permanent Redirect guarantees that the method and request body will be preserved, making it the preferred choice for permanent redirects of non-GET requests.