Fix naming of path and path_prefix parameter names

[waxlamp]

The meanings of these two parameters are reversed in the following places:

• dandisets_versions_assets_list, where path should be called path_prefix:

  dandi-archive/dandiapi/api/views/asset.py

  Line 388 in 83d3a10

  def list(self, request, *args, **kwargs):

• dandisets_versions_assets_paths, where path_prefix should be called path:

  dandi-archive/dandiapi/api/views/asset.py

  Line 425 in 83d3a10

  def paths(self, request, versions__dandiset__pk, versions__version, **kwargs):

It would also be good to improve the Swagger documentation for these endpoints to better explain what they do and what the parameters mean. In particular, the usage of the glob parameter for dandisets_versions_assets_list.

This is a breaking change. We will need to update the web application and the CLI to match the new (correct) parameter names.

See #444 for original discussion and context.

[yarikoptic]

FWIW I just ran into this issue with having multiple assets listed for a path whenever I expected one given the name (path).

❯ curl --silent -X 'GET' 'https://api.dandiarchive.org/api/dandisets/000029/versions/draft/assets/?path=test1234&metadata=false' -H 'accept: application/json' | jq .
{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "asset_id": "bb612483-0a97-4309-9763-7fb518265c70",
      "blob": "0317cf5a-4047-4e19-aae1-4f7b7434d2d7",
      "zarr": null,
      "path": "test12345",
      "size": 9,
      "created": "2023-03-16T15:50:07.184996Z",
      "modified": "2023-03-17T15:41:18.378517Z"
    },
    {
      "asset_id": "28155d24-9342-48bc-a3a7-b69191e86e13",
      "blob": "0317cf5a-4047-4e19-aae1-4f7b7434d2d7",
      "zarr": null,
      "path": "test1234",
      "size": 9,
      "created": "2024-01-31T17:27:07.621838Z",
      "modified": "2024-01-31T17:27:07.641100Z"
    }
  ]
}

[yarikoptic]

@waxlamp what do you think we should do about this? Might be worth bundling with a whatever solution we come up with for

• Add endpoint for querying a folder or asset path in a Dandiset #1837

and may be also related fixes such as for a good old

• /paths should 404 if there are not assets with path_prefix/ #546

[jwodder]

This is a breaking change.

I don't think it needs to be a breaking change. We can just add support for the "correct" query parameters and mark the old ones as deprecated while still supporting them, can't we?

[yarikoptic]

Correct. What names do you suggest to come to replace these current ones?

[jwodder]

@yarikoptic Why wouldn't we just name the new parameters "path_prefix" and "path" as suggested in the original comment?

[yarikoptic]

I missed the fact that we are talking about two different endpoints -- for some reason I thought they both belong to the same end-point. Indeed -- good idea then to just fix it by renaming and having a (potentially very long) deprecation cycle. WDYT @waxlamp ?

[waxlamp]

This is a breaking change.

I don't think it needs to be a breaking change. We can just add support for the "correct" query parameters and mark the old ones as deprecated while still supporting them, can't we?

You're right. This is a good approach. I'll put something together.