microsoft / microsoft/winget-cli-restsource

Documentation differs from Implementation for /packageManifests/{id} return codes (204 or 404)

Open
#170 7 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Issue-Docs
Dominant language
C#
Stars
317
Forks
79
PR merge metrics
No merged PRs in 30d

Description

Brief description of your issue

Hi,

according to both the 1.1.0 and 1.4.0 REST API schema, the /packageManifests/{PackageIdentifier} route is only supposed to return 200, 404 or another error:

https://github.com/microsoft/winget-cli-restsource/blob/main/documentation/WinGet-1.1.0.yaml#L506-L522
https://github.com/microsoft/winget-cli-restsource/blob/main/documentation/WinGet-1.4.0.yaml#L506-L522

However, the reference implementation also explicitly tests for the undocumented 204 here:

https://github.com/microsoft/winget-cli-restsource/blob/main/src/WinGet.RestSource/Helpers/RestSourceTriggerFunctions.cs#L63

which raises the question - should a REST source return 404 like the schema suggests when a packageIdentifier is not found or should it return 204? I have noticed in testing that winget responds with a red error message when it gets a 404 (which I guess is fine / maybe intended?) but responds with a much more calm "no results found" message when it gets a 204 - so the client seems to handle the undocumented 204 more gracefully, further hinting that that's maybe the intended return code and the schema docs are wrong?

Thanks!

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.

Research direction

Read documentation/WinGet-1.1.0.yaml and documentation/WinGet-1.4.0.yaml at the packageManifests route, then compare them with the 204 handling in src/WinGet.RestSource/Helpers/RestSourceTriggerFunctions.cs. Confirm which status code is intended for a missing package and align the schema and reference implementation so their behavior and documentation agree.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.