Many REST APIs return different response *types* based on result count

Open
#107 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
35/100
Issue type
Bug
Clarity
Mostly clear
Activity status
Stale
Tech stack
csharp
Domain
api, backend-api-design

Research direction

Start by tracing the response handling represented by the packages.Items count switch, then inspect the packages, packageManifests, locales, installers, and versions API endpoints. Compare responses for zero, one, and multiple results. Done means each endpoint uses one consistent response shape, with behavior verified through the relevant API checks or tests.

Written by the indexing model from the issue text.

Description

Issue-Bug Issue-Feature
Brief description of your issue

I just hit upon something in the REST api that I believe we should consider changing at the schema/interface level. Some of the APIs return different result types depending on the count of items returned, for example:

        return packages.Items.Count switch
        {
            0 => new NoContentResult(),
            1 => new ApiObjectResult(new ApiResponse<Package>(packages.Items.First(), packages.ContinuationToken)),
            _ => new ApiObjectResult(new ApiResponse<List<Package>>(packages.Items.ToList(), packages.ContinuationToken)),
        };

Either No Content (null), a single object, or an array. For example:

This returns an array: .../api/packages/Microsoft.PowerToys/versions

{"Data":[{...},{...},,…],"ContinuationToken":"…"}

This returns a single object: .../api/packages/Zwift.Zwift/versions

{"Data":{...}}

This returns 204 (null): .../api/packages/Foo.Bar/versions

If the query returns more than one result, I get an object where Data is an array (and there’s a continuationToken property), but if there’s only one result, then Data is an object. This is true for the packages, packageManifests, locales, installers and versions APIs.

IMO this is a bad practice and requires clients to try to parse the result object twice in a catch block to successfully deserialize it. Instead we should always consistently return the same object type, potentially with only one item in the array, and a null continuationToken.

Steps to reproduce

Call above APIs

Expected behavior

Response type should be consistent regardless of # of results

Actual behavior

Response type varies based on number of results

Environment
N/A
Dominant language
C#
Stars
317
Forks
79
No merged PRs in 30d

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from microsoft/winget-cli-restsource

All issues in microsoft/winget-cli-restsource

Similar issues

More C# issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.