[SERVER-55444] APIStrictError should describe how to migrate from unversioned APIs Created: 23/Mar/21  Updated: 29/Oct/23  Resolved: 28/Jun/21

Status: Closed
Project: Core Server
Component/s: Query Language
Affects Version/s: None
Fix Version/s: 5.0.0-rc5, 5.1.0-rc0

Type: Improvement Priority: Major - P3
Reporter: A. Jesse Jiryu Davis Assignee: Maddie Zechar
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Backports
Related
Backwards Compatibility: Fully Compatible
Backport Requested:
v5.0
Sprint: Query Optimization 2021-05-17, Query Optimization 2021-06-28
Participants:

 Description   

When a client tries to use a feature that's not in API Version 1, if the client passes apiVersion: "1" and apiStrict: true, the server replies with APIStrictError. In as many cases as possible, let's accompany the error with a message describing how to migrate to the Versioned API. E.g., when "mapreduce" returns APIStrictError, it should say, "Use aggregate instead", and link to the docs. Ideally, there is a page in the docs that helps users rewrite their mapreduce jobs as aggregations.

Similar for "distinct" (if we choose not to include it in Version 1), and other unversioned APIs with versioned alternatives.



 Comments   
Comment by Vivian Ge (Inactive) [ 06/Oct/21 ]

Updating the fixversion since branching activities occurred yesterday. This ticket will be in rc0 when it’s been triggered. For more active release information, please keep an eye on #server-release. Thank you!

Comment by Githook User [ 25/Jun/21 ]

Author:

{'name': 'Maddie Zechar', 'email': 'mez2113@columbia.edu', 'username': 'madelinezec'}

Message: SERVER-55444: APIStrictError directs user to docs for migration suggestions
Branch: v5.0
https://github.com/mongodb/mongo/commit/9d535c51e86246b21a2ca3f36fcde418020c40e4

Comment by Githook User [ 24/Jun/21 ]

Author:

{'name': 'Maddie Zechar', 'email': 'mez2113@columbia.edu', 'username': 'madelinezec'}

Message: SERVER-55444: APIStrictError directs user to docs for migration suggestions
Branch: master
https://github.com/mongodb/mongo/commit/30be200dfcf31bf49073fafe322a2d4998266253

Comment by Maddie Zechar [ 22/Jun/21 ]

hi ethan.zhangjesse, we have shared this with Pawel who is on board with this approach. The server manual writers are prepared to add information on unsupported commands, supported migrations to their existing, centralized API version 1 doc, once they get that info from us. We should have a better idea of who will gather this information and a "due date" for sharing it with the writers in the next couple of days.

Comment by A. Jesse Jiryu Davis [ 18/Jun/21 ]

Right, for certain commands where there is a clear migration path, such as migrating from mapreduce to aggregate, this ticket is my request that we provide command-specific migration instructions.

Comment by Ethan Zhang (Inactive) [ 17/Jun/21 ]

I feel it will be nice to have. I vaguely remember this was brought up in some meetings.

Comment by Maddie Zechar [ 17/Jun/21 ]

another follow up question for ethan.zhang ana.meza jesse: currently, the server manual has a single, centralized page detailing the commands supported in API Version 1 and how to use them. You can see it here: https://docs.mongodb.com/v5.0/reference/versioned-api/#api-v1-commands

Is this sufficient? Or do we also want information on commands not supported in API Version 1, how to migrate (eg use aggregate instead of map reduce), or some information on the APIStrictError ? cc jeffrey.allen

Comment by Maddie Zechar [ 17/Jun/21 ]

That makes sense jesse! I apologize for all the pings. I wanted to correct my comment after reading the doc a little more.

Jacob and I want to confirm the commands not supported in version 1. The doc mentions that any commands not listed are not supported in API Version 1. Is there a list somewhere (of all mongo commands) that Jacob and I could refer to, so we could cross reference it with the commands that are supported (and deduce from that a complete list of all commands not supported)?

Comment by A. Jesse Jiryu Davis [ 17/Jun/21 ]

If the user calls distinct (etc) with apiStrict: true the command fails with an error message every time, and the error message is returned to the user. So, I opened this ticket to propose that the error message (which must be returned 100% of the time) provide instructions to fix the user’s mistake.

Logging to the log file, in contrast, COULD be reduced to a fraction of the times this error occurs. But this error should be rare (it’s a user mistake, they’ll discover it in testing and correct it immediately) so on second thought let’s do nothing special about rate-limiting the log message.

Comment by A. Jesse Jiryu Davis [ 17/Jun/21 ]

I’m not sure what you mean by “log to the user”. Every error returned in the command reply should include an informative message. I think it should be logged to the log file as often as other command errors due to user mistakes. Eg however often we log “unrecognized operator” or “unrecognized command name”, this error is comparable.

Comment by Jacob Evans [ 27/May/21 ]

We should avoid producing messages here for the commands covered by deprecation messages as part of PM-2251.

Comment by A. Jesse Jiryu Davis [ 24/Mar/21 ]

Those all sound like reasonable ideas to me!

Comment by Ethan Zhang (Inactive) [ 23/Mar/21 ]

Can this be handled in idl in a more generic way?

Should we pass this to the docs team to create some messages first?

Instead of giving customized suggestions for each feature, can we create a centralized doc page and just provide a link to this page in the error message?

Comment by Ana Meza [ 23/Mar/21 ]

We think this is just a matter of documentation and should probably not involve code changes, passing over to QO to take a look

Generated at Thu Feb 08 05:36:29 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.