Should GET Requests Have Request Bodies? REST Guide

HTTP GET requests technically can include a request body according to the HTTP/1.1 specification, but doing so is strongly discouraged due to compatibility issues and violates REST principles. Most HTTP clients including the Fetch API, XMLHttpRequest, and Angular HttpClient explicitly prevent sending bodies with GET requests, which can cause significant interoperability problems across different platforms and browsers.

Contents

• HTTP Specification Context
• REST API Design Principles
• Client Implementation Issues
• Compatibility Problems Across Platforms
• Alternative Approaches for Complex Parameters
• Best Practices Recommendations

HTTP Specification Context

The HTTP/1.1 specification provides nuanced guidance on GET request bodies. According to RFC 7231 §4.3.1, a payload within a GET request message has “no defined semantics.” This means that while the specification doesn’t explicitly forbid bodies in GET requests, it doesn’t assign any meaning to them either.

“A payload within a GET request message has no defined semantics; sending a payload body on a GET request might cause some existing implementations to reject the request.”

This ambiguity creates several problems. While technically possible to send a body with a GET request, servers should not treat the body as having any semantic meaning, which defeats the purpose of including complex parameters in the first place. The specification clarifies that the request method determines whether an entity-body is allowed, and GET is one of the methods where the semantics are restricted.

REST API Design Principles

RESTful API design principles strongly discourage using request bodies with GET methods. According to Speakeasy’s API design guidelines, “it is very frowned upon to use a request body for the HTTP method GET, but expected for POST, PUT, PATCH, and QUERY.”

The core REST principle that governs this is the idempotency and safety of GET operations:

• GET requests should be safe (not modify server state)
• GET requests should be idempotent (multiple identical requests have the same effect)
• GET requests should retrieve resources, not send data to be processed

When you include a request body in a GET request, you’re essentially using GET for data processing rather than resource retrieval, which violates these fundamental REST principles. The Zalando RESTful API guidelines further emphasize that POST should be used for scenarios that cannot be covered by other methods sufficiently.

Client Implementation Issues

Modern HTTP clients have varying levels of support for GET requests with bodies, but most either explicitly prevent it or behave unpredictably:

Fetch API: The MDN documentation clearly states: “You cannot include a body with GET requests.” This is a deliberate design choice that aligns with REST principles and prevents confusion.

XMLHttpRequest: According to multiple sources, XMLHttpRequest doesn’t allow request bodies for GET or HEAD requests. This implementation detail affects many JavaScript libraries that use XHR under the hood.

Angular HttpClient: As noted in Stack Overflow discussions, Angular does not support supplying a body with a GET request, and there’s no workaround because this restriction comes from the underlying XMLHttpRequest API.

Axios: When running in browser environments, Axios defaults to XMLHttpRequest which doesn’t allow GET bodies. While Node.js environments might handle it differently, this creates cross-environment inconsistencies.

These implementation differences mean that any web service expecting GET requests with bodies will fail in many common client environments.

Compatibility Problems Across Platforms

Even beyond JavaScript clients, various HTTP implementations handle GET with bodies inconsistently:

Browser Inconsistencies: Different browsers may handle GET requests with bodies in different ways, some allowing it while others rejecting it outright. This creates a cross-browser compatibility nightmare.

Server Implementation Variations: Some servers may reject GET requests with bodies entirely, while others might accept them but ignore the body contents. This unpredictability makes it impossible to rely on consistent behavior.

Error Handling: Clients attempting to send GET requests with bodies may encounter various error codes:

• 411 Length Required: When servers expect a Content-Length header that’s not typically included in GET requests
• 400 Bad Request: When servers explicitly reject GET methods with bodies
• Connection errors: When client implementations simply don’t support the operation

CORS Issues: Cross-Origin Resource Sharing rules may compound these problems, especially when dealing with different browser security policies.

The Microsoft Azure Architecture Center warns that while you can technically design APIs in certain ways, you should ensure compatibility across different client implementations.

Alternative Approaches for Complex Parameters

Instead of using GET with request bodies, consider these REST-compliant alternatives:

Query String Parameters: For sorting criteria and other simple parameters, the query string remains the most appropriate location. While URLs have length limitations (typically 2048 characters), most modern servers handle much longer URLs.

POST for Search Operations: When you need complex parameter specifications, especially XML-based requests, POST is the appropriate method. The search operation itself becomes the resource being acted upon.

HTTP QUERY Method: Some APIs implement a custom QUERY method that sits between GET and POST, providing a semantic way to send complex parameters while maintaining RESTful design principles.

Resource-Oriented Design: As restfulapi.net suggests, design your URIs to represent resources rather than actions. Instead of complex parameters, create appropriate resource endpoints.

The Moesif API design guide provides excellent examples of when to switch from query parameters to POST based on parameter complexity.

Best Practices Recommendations

Based on the research findings, here are the key recommendations for your RESTful web service:

1. Avoid GET with Bodies: Stick to query string parameters for GET requests, even if the HTTP specification technically allows bodies.

2. Use POST for Complex Data: When clients need to send complex parameter specifications like XML, use POST requests with proper media types.

3. Consider API Versioning: As noted in the ONAP RESTful API guidelines, ensure your API changes are backwards compatible by implementing proper versioning.

4. Document Limitations: If you absolutely must support GET with bodies (not recommended), document this clearly and provide client-side workarounds.

5. Test Across Clients: Thoroughly test your API implementation across different HTTP clients, browsers, and platforms to ensure consistent behavior.

6. Follow Standards Compliance: Adhere to RFC standards and common REST practices to ensure maximum compatibility and adoption.

The Baeldung on Computer Science article provides a comprehensive technical explanation of why GET requests shouldn’t have bodies, emphasizing both specification compliance and practical implementation concerns.

Conclusion

While HTTP/1.1 doesn’t explicitly forbid request bodies in GET requests, doing so is inappropriate for RESTful web services due to multiple compatibility issues. Most HTTP clients prevent sending bodies with GET requests, creating significant interoperability problems across different platforms and browsers. Instead of forcing complex parameters into GET request bodies, use query strings for simple parameters and POST requests for complex data specifications. This approach maintains REST principles, ensures maximum compatibility, and follows established API design best practices that will make your web service more reliable and easier to consume across different client environments.

Sources

1. HTTP GET with request body - Stack Overflow
2. Request Body Best Practices in REST API Design | Speakeasy
3. An Ultimate Guide on HTTP GET with Request Body
4. Why an HTTP Get Request Shouldn’t Have a Body | Baeldung
5. HTTP GET with Request body - Guidelines | TheCodeBuzz
6. Best practices for REST API design - Stack Overflow
7. Using the Fetch API - MDN
8. XMLHttpRequest doesn’t allow request body for GET or HEAD · GitHub Issue
9. REST API HTTP GET with Body - Stack Overflow
10. Web API Design Best Practices - Azure Architecture Center