APIM returning 404 when mandatory query parameter is not provided

Question

I have an APIM instance with an OpenAPI spec imported. One of the endpoints has a mandatory query parameter, with application-level validation.

When I call the endpoint without the mandatory query parameter, APIM doesn't match the URL, and returns a 404 response:

{  
    "statusCode": 404,  
    "message": "Resource not found"  
}  

However, I want the request to be validated by the application, so I can return a meaningful 400 response to the client. Is this possible without making the parameter optional in my OpenAPI spec?

I've tried adding a validate-content policy statement as per https://learn.microsoft.com/en-us/azure/api-management/validation-policies#actions, bit I still get a 404 error.

Others have hit the same issue:

• https://social.msdn.microsoft.com/Forums/azure/en-US/66d39a0e-136a-44a9-a63b-823b360bf976/required-query-parameters-are-part-of-the-url?forum=azureapimgmt
• https://stackoverflow.com/questions/66121750
• https://vmsdurano.com/dirty-hack-on-making-the-required-querystring-params-to-work-in-azure-apim/

Answer 1

I can't seem to submit this as a comment replying to @MayankBargali-MSFT , so let's try it as an answer:

This behaviour "by design" is unhelpful, costly, and from many people's perspectives it is flat-out wrong.

Firstly it coerces an infrastructure component's design philosophy & implementation decision on to users of APIM & the importer - or forces unnecessary workarounds. It seemingly prevents the application handling these client errors in a uniform fashion, e.g. by returning a standard API error response. It may also make it harder for applications to determine how many callers are hitting this issue by fragmenting application-specific logs across infrastructure components.

Secondly, it is quite common for REST-based APIs to return HTTP 400 when a required query parameter is missing, so this preference SHOULD be supported by APIM and the importer.

Thirdly HTTP 404 risks deceiving developers and client software because many developers and a lot of REST client library code interprets HTTP 404 as a signal that the REST endpoint is not found, rather than the endpoint being found but requires a query parameter that was not supplied.

Fourthly if one insists that HTTP 400 is simply not valid for the omission of a required query parameter then arguably HTTP 410 is a better choice than HTTP 404 because unlike HTTP 404 it indicates that the URI (including the query parameters) in question is intentionally unavailable and that condition is expected to be permanent. And that speaks to the point that APIM and its OpenAPI importer should NOT be forcing design philosophy and implementation decisions that are significantly contested by API designers on to APIM users.

Answer 2

@Chris Parton Thanks for sharing more details. Yes, this is expected behavior as documented here.
When you mark query string parameters as required in your swagger definition, APIM will import the parameter as URL template parameter which is by design.
If template parameter is not provided, the URL which defines the API itself is not complete thus APIM cannot match the API's then returning 404. This has been designed behavior of API Management from the beginning.

You can either:

• Manually change via form-based editor in Azure Portal, or
• Remove the "required" attribute from the Open API definition, thus not converting them to template parameters.

Unfortunately, as of now there are no plans to change this behavior in the near term. While we understand this is not ideal behavior for your scenario, but as this is used by other customers which may be depending on this behavior (returning 404 instead of 400).

You can submit a feature request here so the product team can implement the feature which can control this behavior. The default behavior can be 404 but customers can override to 400 as per their requirement. I have also passed this feedback to our team but will suggest you to post the same as feature request in our feedback forum.