feat(api): Add sortOrder to API_GetComments

[ioslife]

Alter the GetComments endpoint from #2552 to add a sortOrder query param

/*
*  API_GetComments - returns the comments associated to a game or achievement
*    i : game or achievement id or username
*    t : 1 = game, 2 = achievement, 3 = user
*    o : offset - number of entries to skip (default: 0)
*    c : count - number of entries to return (default: 100, max: 500)
*    s : sortOrder - sort comments. 'submitted' = ascending, '-submitted' = descending (default: 'submitted')
*
*  int         Count                       number of comment records returned in the response
*  int         Total                       number of comment records the game/achievement/user actually has overall
*  array       Results
*   object      [value]
*    int         User                      username of the commenter
*    string      Submitted                 date time the comment was submitted
*    string      CommentText               text of the comment
*/

[ioslife]

FYI – I am open to a different query letter here

[wescopeland]

This could be too ambiguous in terms of what the orderBy() is. I'm also thinking integers as possible values may be inflexible if this pattern is extended to other API endpoints.

I think we may want to change this to use JSON:API-like enum values, ie: createdAt and -createdAt.

[Jamiras]

We do have a few public APIs where filter parameters are effectively booleans (0=all,1=filtered), and some that are direct mapping of enums (3=core,5=unofficial).

But as this is not an enum, and it's not being implemented as a boolean (s: sort descending (0=no,1=yes)), I agree that it makes sense to have it be more free-form.

[ioslife]

Cool, I will check on this next week. Thanks for looking at it

[ioslife]

Hello, it is I! Finally making finishing this a priority, apologies for the PR and run.

I just pushed a commit that accepts submitted and -submitted as the s param. I am willing to add others to the sortOptions enum, but wanted to verify this is the pattern you were thinking @wescopeland.

[wescopeland]

Yep, I think so. I would rename it to sort to align with some of our other paths like: https://retroachievements.org/games?sort=-achievementsPublished

[Jamiras]

We do have a few public APIs where filter parameters are effectively booleans (0=all,1=filtered), and some that are direct mapping of enums (3=core,5=unofficial).

But as this is not an enum, and it's not being implemented as a boolean (s: sort descending (0=no,1=yes)), I agree that it makes sense to have it be more free-form.

[wescopeland]

LGTM - we just need an accompanying docs PR before we can ship this in a release.

[ioslife]

LGTM - we just need an accompanying docs PR before we can ship this in a release.

Awesome, thanks! Will push docs PR tomorrow.

[ioslife]

@wescopeland added in RetroAchievements/api-docs#79