Permanent Redirect

# Quick Definition

The 308 Permanent Redirect status code indicates that the target resource has been assigned a new permanent URI. Unlike a 301, the 308 requires the client to preserve the original HTTP method and request body when following the redirect. A POST remains a POST, a PUT remains a PUT -- the method is never changed to GET.

# When Does a 308 Redirect Occur?

A 308 redirect is used when a resource has permanently moved to a new URL and it is critical that the HTTP method be preserved during the redirect. This is particularly important for API endpoints where clients send POST, PUT, or DELETE requests -- changing these to GET (as 301 allows) would break the intended operation.

Common scenarios include API version migrations (e.g., /api/v1/users permanently moving to /api/v2/users), domain changes for API services, and restructuring URL paths for endpoints that accept non-GET methods.

# Common Use Cases

• API endpoint migrations where POST/PUT/DELETE methods must be preserved through the redirect
• Domain changes for REST APIs (e.g., moving from api.old.com to api.new.com)
• URL restructuring for webhook endpoints that receive POST requests
• HTTPS enforcement for API endpoints where method preservation is critical
• Moving API versioned paths while maintaining backward compatibility for all HTTP methods

# Best Practices

1. Use 308 instead of 301 for APIs -- If your API endpoints accept POST, PUT, or DELETE requests, always use 308 to ensure clients don't silently change the method to GET when following the redirect.
2. Keep 301 for browser-facing content -- For web pages that only serve GET requests, 301 is perfectly fine and has broader legacy support. Reserve 308 for cases where method preservation matters.
3. Update API documentation promptly -- While the 308 redirect ensures backward compatibility, update your documentation to point to the new URL so clients can update their code.
4. Set appropriate cache headers -- Since 308 is permanent, clients and intermediaries will cache it. Ensure your Location header is correct before deploying, as correcting a cached 308 is difficult.
5. Test with all HTTP methods -- Verify that POST, PUT, PATCH, and DELETE requests all follow the redirect correctly with method and body intact.

# HTTP Example

POST /api/v1/users HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "name": "Jane Doe",
  "email": "jane@example.com"
}

HTTP/1.1 308 Permanent Redirect
Location: https://api.example.com/api/v2/users

POST /api/v2/users HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "name": "Jane Doe",
  "email": "jane@example.com"
}

# Related Status Codes

# Frequently Asked Questions