question

ChrisParton-4099 avatar image
0 Votes"
ChrisParton-4099 asked MayankBargali-MSFT edited

APIM returning 404 when mandatory query parameter is not provided

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://docs.microsoft.com/en-us/azure/api-management/validation-policies#actions, bit I still get a 404 error.

Others have hit the same issue:

azure-api-management
· 2
5 |1600 characters needed characters left characters exceeded

Up to 10 attachments (including images) can be used with a maximum of 3.0 MiB each and 30.0 MiB total.

@ChrisParton-4099 Thanks for reaching out. Can you please confirm if you are referring to query parameters and not the template parameter?
Query Parameter: /API/operation?param1=value
Template Parameter: /API/operation/{id}

In case if it the query parameter with required checked then I don't see the APIM is returning 404 error as per the test performed at my end. Only in case your backend service needs query parameter then the 404 error should be returned from your backend service rather than APIM. Can you review the OCP-APIM-Trace to validate whether the 404 error is returned from your backend service? In case if 404 error is return from APIM then OCP APIM location will be empty.

0 Votes 0 ·

Hi @MayankBargali-MSFT ,

Thanks for the advice. It appears that when APIM imports an OpenAPI specification, it creates template parameters for any required query parameters (see screenshot), instead of regular query parameters. That will be the cause of the issue.

Do you know if there's a way to change that behaviour?

198645-image.png

I think the expected behaviour would be for a required query parameter to be created instead, like this:
198528-image.png

Here's an OpenAPI spec that reproduces the issue. Removing required: true from the query parameter sets it as a query parameter, as expected.

 openapi: 3.0.0
 info:
   title: Test API
   description: Test
   version: '1.0'
 paths:
   /test/suggestions:
     get:
       summary: Suggestions
       operationId: Suggestions
       parameters:
         - name: q
           in: query
           schema:
             type: string
           required: true
       responses:
         '200':
           description: 'Success'


0 Votes 0 ·
image.png (4.8 KiB)
image.png (5.3 KiB)
MayankBargali-MSFT avatar image
0 Votes"
MayankBargali-MSFT answered

@ChrisParton-4099 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.

5 |1600 characters needed characters left characters exceeded

Up to 10 attachments (including images) can be used with a maximum of 3.0 MiB each and 30.0 MiB total.

RichardMazzaferri-8336 avatar image
0 Votes"
RichardMazzaferri-8336 answered MayankBargali-MSFT edited

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.



· 1
5 |1600 characters needed characters left characters exceeded

Up to 10 attachments (including images) can be used with a maximum of 3.0 MiB each and 30.0 MiB total.

@RichardMazzaferri-8336 Thanks for sharing your candid feedback and I do acknowledge your feedback. I do see the same feature requested created here.

I will pass this feedback internally through different channels to the product team to revisit this feature/feedback and I will also suggest you to post your feedback/upvote here as the product team is continuously monitoring this feedback and implementing/improving the services/products.

0 Votes 0 ·