Doorkeeper: "The redirect uri included is not valid." can be confusing for API consumers

[jmealo]

Kudos on Doorkeeper!

The error message "The redirect uri included is not valid." is ambiguous for developers consuming an API.

I realize that this is thrown from a catch / rescue statement as a last resort, however, it'd be helpful if it said that it failed validation rather than it being invalid.

To me the latter sounds as if the URL was not passed correctly or is in an invalid format (rather than it failing to match a domain/url expected by the API).

Regards,
Jeff

[tute]

What exactly is the change that you would like to see?

[jmealo]

The wording for each of these serve to demonstrate the added clarity as we ramp up verbosity and specifically target both API providers and consumers.

Good:
"The well-formed redirect URI ($value) included in your request failed custom validation logic."

• The value that I sent was received.
• The value is everything that a URI should be.
• I did not make a typo, $value is what I meant to send.

Better:
"The well-formed redirect URI ($value) included in your request failed custom validation logic implemented by the API provider. Please contact the API provider for more information on why validation failed."

• Doorkeeper did not decide the URI was invalid. I do not need to bug them or review their code, the API provider added additional custom logic. I should bug the API provider or review their documentation and/or code samples.

Best:
"The well-formed redirect URI ($value) included in your request failed custom validation logic implemented by the API provider. API consumers should contact the API provider. API providers should return a helpful error message to consumers when custom validation fails (see: ).

• As a consumer: I know what to do and will mention that they could have provided a custom error when I finally elevate it to support. Providing a copy of this error message also serves to alert the implementor that they could have prevented this support request.
• As an implementor: I am likely to be made aware of the ability to provide custom error messages by reading the code, getting a support ticket, during QA or through testing.

@tute: My request may seem ridiculous on the surface, however, the amount of effort to improve this error message, which will snowball into better error messages all around will save hundreds if not thousands of man hours over time due to the sheer number of Doorkeeper deployments.

[tute]

I also think better error messages is something we should care about.

I don't see custom logic for URL validation though. All I see is potential for splitting "uri not present" and "uri included is not valid" messages. I would accept a PR with that change, and if there is room for more please let me know.

Thank you for your clear explanation.

[nbulaj]

Hi @jmealo . Do you still interested in this issue?

I read the conversation, but can't guess why you always mentioned _"custom validation logic implemented by the API provider"_ ?

I agree with something like "_Requested well-formed redirect URI ($value) doesn't match client redirect URI_", what do you think?

[nbulaj]

I've changed description message to be more informative (this error occurs when URI is malformed or does n't match client redirect URI).

If anybody found it not informative - PRs are very welcome!

[jmealo]

Thanks.

I was interacting with an API that was based on doorkeeper. These catch all errors can obscure API logic errors. It's not always an internal developer in your organization who has access to the API code. Making these errors more descriptive is very important for figuring out cross organizationally where the issue is. It should be obvious to an API consumer whether they are sending an invalid request or there's a bug in the API. This can end up being weeks or months of back-and-forth depending on the responsiveness of the API provider.

"API provider" being anyone who provides an API to be consumed by users external to their organization.

I realize this is a lot to take on in a single ticket but I wanted to make sure I was clear and why I think this is important to handle upstream.

Thank you for taking my concerns seriously and working to improve error messages. They are the UI/UX for APIs :-)

(( If you consider this a people problem and not a technical problem: I don't disagree with that. However, we can use technology to make it better for everyone. ))