Designing /api/v2

After discussing with Peter on Slack, let’s start a discussion about what v2 might look like:

These are the endpoints we have now:

/chrom-sizes/
/uids_by_filename/
/tilesets/
/tileset_info/
/tiles/
/register_url/

If this were RESTful, how many resources would there be? I think there’s just 3:

• /chrom-sizes/ or /coord-systems/
• /tilesets/
• /tiles/

/register_url/ ideally should be some kind of POST request to /tilesets/… a way to register a new remote tileset.

/tileset_info/ would just be a GET request to /tilesets/ with a id parameter

/uids_by_filename/ would just be a different GET request to /tilesets/

Thoughts?

[nvictus]

Even putting v2 aside, maybe we should have a proper API reference for all v1 endpoints (http://docs.higlass.io/higlass_server.html#api)

[alexpreynolds]

Does use of tilesets?ac=foo do the same as uids_by_filename?

$ curl -qL “http://127.0.0.1/api/v1/tilesets?ac=foo” | jq .results[0].uuid “Vuol_ez-QlO98FsSgtwLyQ”

I didn’t know that tilesets could point to the same filename. I thought that ingesting a tileset adds a suffix if the filename already exists.

Non-RESTful utility endpoints are helpful. Using filter options with existing endpoints works, too, but the higlass API documentation might lack some detail on these (https://docs.higlass.io/higlass_server.html#api). It is definitely helpful to be able to get UUIDs from filenames for my use case, but I had to dig into the higlass-server code to find other filter options.

I don’t have much useful to add to the v2 discussion, but thought a perspective from the user side about endpoints might be helpful.

On Tue, May 7, 2019 at 10:06 AM Peter Kerpedjiev [e-mail] wrote:

I’m not aware that we’re actually using uids_by_filename for anything. It’s a good function to have for checking before deleting tilesets. In an ideal world, each tileset should point to its own file. In the less than ideal world that we live, multiple tilesets could point to the same file.

When deleting a file, all tilesets should be checked to make sure they don’t point to it.

which is the minimal set for a track source server

What’s your definition of a minimal track source server? For viewing data, only /tileset_info and /tiles are necessary. For listing available tilesets we add /tilesets. For saving viewconfs /viewconfs.

There are often cases where I only implement tileset_info and tiles because I use higlass-python to view a dataset and I’m not interested in having it listed in the track listings, storing viewconfs or using hipiler.

With that said, I think your classification makes a lot of sense. Most important, IMO, is documentation for the current API. I know flask has some add-ons that auto-document APIs and Django probably does too. Haven’t spent enough time looking at them to be familiar.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/higlass/higlass/issues/642#issuecomment-490166305, or mute the thread https://github.com/notifications/unsubscribe-auth/AAAIGMHIDZMPCIJV2VJB6Z3PUGZILANCNFSM4HKWY5CA .