Technical Analysis of Resolving HTTP 405 Method Not Allowed Error in Web API PUT Requests

Problem Background and Error Phenomenon

In ASP.NET Web API development, developers frequently encounter HTTP 405 Method Not Allowed errors when making PUT requests. This error typically occurs when attempting to update a resource, where the client sends a PUT request to the server, but the server rejects the HTTP method. From the provided case, the developer faced this issue while using the HttpClient.PutAsJsonAsync method, despite seemingly correct route configurations and controller methods.

Error Cause Analysis

The HTTP 405 error indicates that the server recognizes the request URI but does not support the HTTP method used. In the ASP.NET environment, this is often related to the WebDAV (Web Distributed Authoring and Versioning) module. WebDAV is an extension of the HTTP protocol for collaborative editing and management of web resources, but it can override or interfere with standard RESTful methods like PUT and DELETE. Even if developers do not explicitly install WebDAV, certain IIS configurations or default settings may enable its module, leading to interception of PUT requests.

In the case study, the route configuration defines multiple routes, including a default API route and a specific route for GET methods. Although the PUT method is correctly defined in the ApiController, the WebDAV module might prioritize request handling, resulting in a 405 error. This highlights the importance of IIS module processing order and how configuration adjustments can resolve conflicts.

Solution: Removing the WebDAV Module

Based on best practices, the core step to resolve this issue is modifying the Web.config file to remove the WebDAV module and handler. This ensures that PUT and other HTTP methods are not intercepted by WebDAV. The specific steps are as follows:

First, add module configuration in the <system.webServer> section:

<modules runAllManagedModulesForAllRequests="true">
    <remove name="WebDAVModule"/>
</modules>

Here, runAllManagedModulesForAllRequests="true" ensures all managed modules handle all requests, and <remove name="WebDAVModule"/> explicitly removes the WebDAV module. This prevents the module from interfering with PUT requests.

Second, add similar configuration in the handlers section:

<handlers>
    <remove name="WebDAV"/>
    ...
</handlers>

By removing the handler named "WebDAV", potential conflicts are further eliminated. It is recommended to apply these modifications in the Web.config of both the Web API project and the front-end project to ensure consistency.

Code Examples and Implementation Details

To better understand the issue, let's refactor the code from the case study. In the Web API Department controller, the PUT method is defined as follows:

public HttpResponseMessage Put(int id, Department department)
{
    if (!ModelState.IsValid)
    {
        return Request.CreateErrorResponse(HttpStatusCode.BadRequest, ModelState);
    }
    if (id != department.Id)
    {
        return Request.CreateResponse(HttpStatusCode.BadRequest);
    }
    db.Entry(department).State = EntityState.Modified;
    try
    {
        db.SaveChanges();
    }
    catch (DbUpdateConcurrencyException ex)
    {
        return Request.CreateErrorResponse(HttpStatusCode.NotFound, ex);
    }
    return Request.CreateResponse(HttpStatusCode.OK);
}

This method checks model state and ID matching, then updates the database. If the WebDAV module is not removed, even with correct code, the PUT request may fail. In the front-end MVC controller, the PUT request is sent using HttpClient:

response = client.PutAsJsonAsync(string.Format(contactUri.PathAndQuery), department).Result;

By applying the Web.config modifications, this call will execute successfully, returning an HTTP 200 status code.

Additional Knowledge and Best Practices

Beyond removing WebDAV, developers should ensure proper route configuration. In the provided WebApiConfig, the route template api/{controller}/{id} should match the URI of PUT requests. For example, a PUT to api/department/5 should route to the Put method of the Department controller. If routes do not match, it could also lead to a 405 error.

Additionally, consider using attribute routing to explicitly define HTTP methods. For instance, add the [HttpPut] attribute to ApiController methods:

[HttpPut]
public HttpResponseMessage Put(int id, Department department)
{
    // Method implementation
}

This enhances code readability and maintainability. Meanwhile, it is advisable to test all HTTP methods in development environments using tools like Postman to validate API behavior.

Conclusion

The HTTP 405 Method Not Allowed error is common in Web API development, primarily due to interference from the WebDAV module. By modifying Web.config to remove the WebDAV module and handler, the issue can be effectively resolved. This article, based on a real-world case, provides detailed analysis and solutions to help developers build stable RESTful APIs. After implementing these steps, PUT requests will process normally, improving application reliability and user experience.