Add the orderBy parameter to list methods

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:

@andrii-bodnar

@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"

@halfwind22

@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

@andrii-bodnar

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?

@halfwind22

@halfwind22 yes

Thanks, please assign this to me.

@andrii-bodnar

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

@halfwind22

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

@andrii-bodnar

// 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??

@halfwind22

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

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 .

Sounds good to me 🚀

@korzol

@korzol Thank you! Some work had already been done, please take a look at the previous discussion in the comments. Also, the methods listed in the task description might be irrelevant (the description may not include all the methods that accept orderBy)

@andrii-bodnar

@andrii-bodnar Sure! I’ll first check the .NET implementation, then review the work that’s already been done. After that, if everything looks good, I’ll start coding. Also, I’ll go through the documentation of all API list methods to ensure no methods are missed.

@andrii-bodnar

@andrii-bodnar I've checked the .NET implementation. There are three overloaded ListTasks methods for the Task API:

public Task<ResponseList<TaskResource>> ListTasks(
    long projectId,
    int limit = 25,
    int offset = 0,
    TaskStatus? status = null,
    long? assigneeId = null,
    IEnumerable<SortingRule>? orderBy = null)
{
    return ListTasks(projectId, new TasksListParams(limit, offset, status, assigneeId, orderBy));
}

public Task<ResponseList<TaskResource>> ListTasks(
    long projectId,
    int limit = 25,
    int offset = 0,
    IEnumerable<TaskStatus>? statuses = null,
    long? assigneeId = null,
    IEnumerable<SortingRule>? orderBy = null)
{
    return ListTasks(projectId, new TasksListParams(limit, offset, statuses, assigneeId, orderBy));
}
        
public async Task<ResponseList<TaskResource>> ListTasks(long projectId, TasksListParams @params)
{
    string url = FormUrl_Tasks(projectId);
    CrowdinApiResult result = await _apiClient.SendGetRequest(url, @params.ToQueryParams());
    return _jsonParser.ParseResponseList<TaskResource>(result.JsonObject);
}

These overloads differ in parameters, and the first two delegate to the third one, which takes a TasksListParams DTO containing all additional/optional parameters.

This structure is similar to what I did for supporting multivalued status in listTasks.
Would you like me to follow the same pattern across all APIs — i.e., introduce a DTO-based overload and refactor the existing list methods to delegate to it?

I think it's overly complicated in most cases. I quickly checked the other API executors in the .NET Client, and I found that some List methods just have an additional optional parameter. I believe we can do the same. However, for the listTasks method, where we already have overloaded methods, we'll have to keep that approach.

The main goal is to keep it simple, usable, and backward-compatible :)

@andrii-bodnar

Hi @andrii-bodnar,

I believe the core sorting functionality is implemented. I've added support for sorting in the listTasks method by overloading it with additional parameter.

Tests for this case are also included.

Could you please review the current state of the implementation?

If everything looks good, I’ll proceed with adding sorting support to the remaining relevant methods.

Here’s the PR: #335

Thanks in advance!

@korzol

Hi @korzol, thanks a lot for the contribution! I will take a look.

@andrii-bodnar

Hello @andrii-bodnar,

I believe I've completed the implementation of orderBy support across the list methods.

I've covered a few more methods than initially mentioned in the task description — full list is below.

Due to the number of changes, the work is split into multiple commits to help with reviewability.

Could you please take a look when you have a chance and let me know if any adjustments are needed?

Covered methods

Thanks!

@korzol

Hello @korzol, wow, that's huge! 🚀

I just checked the List String Comments docs, and it seems to have the orderBy parameter. I didn't check it with real data. Do you mean that it's documented but doesn't work?

@korzol

@korzol, could we also include a description of this sorting functionality in the Readme? With a simple example.

@andrii-bodnar

@andrii-bodnar

I just checked the List String Comments docs, and it seems to have the orderBy parameter. I didn't check it with real data. Do you mean that it's documented but doesn't work?

No, I must've overlooked it earlier. Will check it again this evening.

@korzol, could we also include a description of this sorting functionality in the Readme? With a simple example.

Absolutely. I'll add a short description and example of the sorting functionality to the README as well.

@andrii-bodnar

@andrii-bodnar Kindly check again the PR. Added orderBy support to List String Comments and updated README.md file

Navigation Menu

Repository navigation

Add the `orderBy` parameter to list methods #235

22 remaining items

Covered methods

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Add the orderBy parameter to list methods #235

Description

Activity

halfwind22 commented on Apr 6, 2024

andrii-bodnar commented on Apr 8, 2024

halfwind22 commented on Apr 8, 2024

andrii-bodnar commented on Apr 9, 2024

halfwind22 commented on Apr 9, 2024

halfwind22 commented on Apr 9, 2024

andrii-bodnar commented on Apr 9, 2024

halfwind22 commented on Apr 9, 2024

andrii-bodnar commented on Apr 9, 2024

halfwind22 commented on Apr 9, 2024

andrii-bodnar commented on Apr 9, 2024

22 remaining items

andrii-bodnar commented on Sep 24, 2025

korzol commented on Sep 24, 2025

korzol commented on Sep 25, 2025

andrii-bodnar commented on Sep 25, 2025

korzol commented on Sep 30, 2025

andrii-bodnar commented on Sep 30, 2025

korzol commented on Oct 11, 2025

Covered methods

andrii-bodnar commented on Oct 13, 2025

andrii-bodnar commented on Oct 13, 2025

korzol commented on Oct 13, 2025

korzol commented on Oct 13, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Add the `orderBy` parameter to list methods #235