Add the `orderBy` parameter to list methods

[andrii-bodnar]

The Crowdin API has been enhanced with a new orderBy parameter in a number of list methods. It allows sorting the results by a specific field in ascending or descending order.

The list of methods that support the new parameter:

• List projects
• List branches
• List directories
• List files
• List strings
• List Translation Approvals
• List Language Translations
• List String Translations
• List String Comments
• List Screenshots
• List Concepts
• List Glossaries
• List Terms
• List TMs
• List TM Segments
• List Tasks
• List User Tasks
• List Project Members
• List Labels
• List Groups (Enterprise only)
• List Users (Enterprise only)
• List Teams (Enterprise only)

References:

• API reference
• Enterprise API reference
• Sorting rules

[halfwind22]

@andrii-bodnar Starting out with open source contributions, I would like to take this up - by when would you want this to be done? Also I believe that this is the functionality that you are looking to implement: https://developer.crowdin.com/api/v2/#section/Introduction/Sorting with the request URL like "https://<hostname>/api/<version>/resource?orderBy=createdAt desc,name,priority asc,title desc"

[andrii-bodnar]

@halfwind22 the new parameter should be added to the methods listed in the description.

For example: the following is the corresponding function for the "List project" method - https://github.com/crowdin/crowdin-api-client-java/blob/master/src/main/java/com/crowdin/client/projectsgroups/ProjectsGroupsApi.java#L122

[halfwind22]

Yes @andrii-bodnar , I absolutely get your point - my question was more around how would the request url would look like https://<hostname>/api/<version>/resource?orderBy=createdAt desc,name,priority asc,title desc probably?

[andrii-bodnar]

@halfwind22 yes

[halfwind22]

Thanks, please assign this to me.

[halfwind22]

@andrii-bodnar I propose to allow users to pass in a Linked Hash map for specifying ordering key and the corresponding ordering sequence(ASC/DESC - enums) . Or would it be better to allow the ordering specification in plaintext. My concern for the second approach is that an incorrect string might be passed , like ?orderBy name,id dsc or maybe missing out on a comma.

[andrii-bodnar]

@halfwind22 could you please provide some examples of what this might look like? I agree that passing raw parameters is unsafe and error-prone.

[halfwind22]

// Client side code
Map<,SortOrder> orderByMap = new LinkedHashmap<String,SortOrder>();
orderByMap.put(name, SortOrder.DESC)
orderByMap.put(id, SortOrder.ASC)

// Method Signature 
listProjects(Long groupId, Integer hasManagerAccess, Integer limit, Integer offset, LinkedHashMap<String, SortOrder> orderByMap)

@andrii-bodnar Above is how regular users would invoke the method. Now users might also want to just skip the SortOrder (which makes it ASC order) , so we might need to have a wrapper around the put() of the Map interface, to handle that scenario. Same goes for duplicate keys. Thoughts??

[andrii-bodnar]

@halfwind22 I'm also curious about how to make the sort order value optional.

I don't think we should care about duplicate values, it's too complicated for this feature.

[halfwind22]

A wrapper over the put() method of Map interface should suffice. A simpler solution would be user entering a key with no value (null type) into the map and then we interpret that null as ASCENDING. We could also probably ignore it ,because the backend REST endpoint can still work with query params coming without a sorting order like ?orderBy name,id desc .

[andrii-bodnar]

Sounds good to me 🚀