skip to content

In ASP.NET Core 10, what happens when a request's path matches a MapGet endpoint but its HTTP method, such as HEAD, does not?

level: juniorimportance: should knowfreq 42%

answer

  1. the path matched, the verb did not
  2. 405 plus an Allow header
  3. a built-in rejection endpoint
  4. MapGet accepts GET only
  5. any-method endpoints suppress the 405

basics

~20 s

Routing answers 405 Method Not Allowed with an Allow header listing the methods the matching endpoints accept, and an empty body. MapGet registers GET only, so a HEAD or POST to that path gets 405, not 404.

solid answer

~40 s

Endpoint routing checks the HTTP method as part of matching. When the path fits one or more endpoints but none accepts the request's method, routing selects a built-in rejection endpoint whose display name is "405 HTTP Method Not Supported"; it sets status 405 and an `Allow` header such as `GET, PUT`, and writes no body. `MapGet` adds GET only, so an uptime monitor sending `HEAD /orders/42` gets 405 with `Allow: GET`; routing does not treat HEAD as GET for you. Two edge cases: if any endpoint at that path accepts every method, such as `app.Map(...)` or a `MapFallback`, routing chooses it instead of answering 405; and a path that matches nothing at all is still a 404.

code

http · 6 lines
http
HEAD /orders/42 HTTP/1.1
Host: api.example.com

HTTP/1.1 405 Method Not Allowed
Allow: GET, PUT
Content-Length: 0

go deeper

for a junior

Recall that a matching path with the wrong method gives 405 with an Allow header, and that MapGet accepts only GET.

for a middle

Explain that the 405 comes from a rejection endpoint selected by routing, with an empty body, and why HEAD probes hit it.

for a senior

Diagnose missing or unexpected 405s: any-method endpoints and fallbacks suppress them, and middleware sees a non-null endpoint for a 405.

for a principal

Agree API-wide method semantics, including HEAD support and whether fallbacks may cover API paths, so clients get consistent 404 and 405 answers.

## How the method takes part in matching In ASP.NET Core 10 every endpoint created by `MapGet`, `MapPost`, `MapPut`, `MapDelete`, `MapPatch` or `MapMethods`, and every controller action with `[HttpGet]`, `[HttpPost]` and friends, carries an **`HttpMethodMetadata`** entry listing the methods it accepts. The routing middleware runs a matcher policy, `HttpMethodMatcherPolicy`, that uses this metadata while it narrows the candidates for the request path. Take a food-delivery API: ```csharp app.MapGet("/orders/{id:int}", (int id) => Results.Ok(new { id })); app.MapPut("/orders/{id:int}", (int id) => Results.NoContent()); ``` | Request | Result | |---|---| | `GET /orders/42` | 200 from the GET endpoint | | `PUT /orders/42` | 204 from the PUT endpoint | | `DELETE /orders/42` | **405**, `Allow: GET, PUT` | | `HEAD /orders/42` | **405**, `Allow: GET, PUT` | | `GET /orders` | 404: no endpoint has that path | ## The rejection endpoint The 405 is not an exception and not middleware magic: the matcher selects a real `Endpoint` built by the policy. In the v10.0.12 source its display name is the constant `"405 HTTP Method Not Supported"`, and its delegate does three things: 1. Sets the `Allow` response header to the accepted methods, sorted and comma-separated. 2. Sets the status code to 405. 3. Writes nothing else; the body is empty. Two consequences follow. Middleware between routing and the endpoint sees a **non-null** endpoint from `HttpContext.GetEndpoint()` even though nothing in your code will run, so a check like "endpoint is null means unmatched" misses 405s. And because the body is empty, middleware that fills in bodies for bare error status codes can add one if you want a ProblemDetails-shaped 405. ## The HEAD surprise HTTP says a HEAD response should match a GET response minus the body, and many load balancers and uptime monitors probe with HEAD. Endpoint routing does **not** map HEAD onto GET endpoints: `MapGet` registers exactly `GET`. A HEAD probe against `/orders/42` therefore gets 405 with `Allow: GET, PUT`, which can make a monitor report the API as down. Fixes: - Point the probe at a GET health endpoint. - Register the route for both methods with `app.MapMethods("/health", new[] { "GET", "HEAD" }, ...)`. ## When you do not get a 405 The policy only adds the 405 endpoint when **no** endpoint at that path accepts every method. Comments in the source explain why: if an app defines an endpoint that handles all verbs but a constraint rejects the request, that is treated as an input problem, not an HTTP-method violation. In practice: - An endpoint mapped with `app.Map("/orders/{id}", ...)` has no method metadata, so it accepts every method and wins instead of a 405. - A fallback from `MapFallback` matches almost every path that has no file extension, accepts every method, and therefore swallows the 405s under it. - A path that matches no endpoint at all is a 404; 405 requires that the **path** matched. - CORS preflight requests (`OPTIONS` with `Origin` and `Access-Control-Request-Method`) are handled separately for endpoints that accept preflight. ## Controllers behave the same way The policy does not care how an endpoint was declared. An MVC action with `[HttpGet("{id:int}")]` carries `HttpMethodMetadata` for GET, so a DELETE to the same path gets the same 405 and `Allow` header. The trap on the controller side is the opposite one: an attribute-routed action with only `[Route("orders/{id:int}")]` and no `[HttpGet]`-style attribute has **no** method metadata, accepts every verb, and so removes the 405 for that path. Mark every API action with an explicit HTTP method attribute. ## Debugging an unexpected 405 1. Read the `Allow` header: it lists what the matching endpoints accept, which usually reveals the mistake, such as `POST` sent to an endpoint mapped with `MapPut`. 2. Check the client's method for the `HEAD` and `OPTIONS` cases above. 3. Turn on `Debug` logging for `Microsoft.AspNetCore.Routing` to see which endpoint routing matched. ## What interviewers listen for - 405 means the path matched and the method did not; 404 means the path matched nothing. - The `Allow` header and the empty body. - `MapGet` is GET-only; HEAD is not implied. - Any-method endpoints and fallbacks suppress the 405.

  • Why does adding app.MapFallback(...) make a DELETE to /orders/42 stop returning 405?
    The fallback is mapped as `{*path:nonfile}` with no HTTP method metadata, so it matches `/orders/42` for every method, at the lowest order. Routing only adds its 405 rejection endpoint when nothing at that path accepts all methods; with the fallback present, the DELETE goes to the fallback instead. Restrict the fallback's pattern or methods if API clients should still see 405.
  • Does middleware between routing and the endpoint see a null endpoint for a 405 request?
    No. Routing selects a real rejection endpoint named "405 HTTP Method Not Supported", so `HttpContext.GetEndpoint()` returns it. Middleware that treats a null endpoint as "unmatched" must also recognise this case, for example by checking the response status after `next` or the endpoint's lack of your own metadata.

  • Says a wrong HTTP method on a matching path returns 404.
  • Assumes MapGet endpoints also answer HEAD requests automatically.
  • Expects the 405 response to carry a ProblemDetails body by default.
  • Thinks the 405 is produced by throwing an exception in the endpoint middleware.
  • Believes a MapFallback endpoint never affects 405 responses for API paths.