Add an api for external apps

[RustyNova016]

It would be nice to have an API to get the information provided by harmony programmatically. Could be useful to have an userscript that warn missing release links for the release, or recordings, etc...

I'd definitly love a way to have the missing recordings links so that I can directly put an edit link in Alistral's MB Clippy, without making the user go to Harmony first

[kellnerd]

Yeah, there will be endpoints which return JSON rather than HTML in the future. They will be needed to build features which dynamically lookup additional sources without leaving the user waiting until the initial page renders.

The recording link actions are definitely a candidate for this, I had already thought about making them opt-in (i.e. fetch them in a separate, optional JSON API call).

Side note: We have to ensure that Harmony can't be abused to query the underlying third party APIs. So any JSON endpoint will only return processed data, and there might be access restrictions for some endpoints.

[FoxxMD]

I'm the developer of multi-scrobbler and have been planning on implementing something adjacent to harmony for awhile now, but the feature has been brought up recently by a user.

It would be amazing to be able to use harmony as a backend for this feature. A few things that would be essential for me:

• Having JSON endpoints
• Querying by more fields, or a combination of fields, rather than only URL/barcode/MBID
  • Many of the services multi-scrobbler receives data from only present artist, title, and album
• Optional authentication for providers, to allow more usage than anonymous access

My current plan is to support Musicbrainz in the near future since multi-scrobbler already leverages it. But in the medium/far term roadmap adding harmony as an additional metadata source be awesome.

[ligeia]

I have a local implementation of this that I'm working on and I can share code once I'm sure it's stable. This feature drastically improves my automation flow, because I could use it to identify gtin unknown (especially with Apple links) without having to actually visit the page, which allows me to move on to the next candidate link more quickly.

[ligeia]

Did some debugging today and I think I'm on track. I'll try to work on a PR this week but I've never done one before so patience will be needed lol.

[ligeia]

I have a better version of an API working now. It essentially atomizes the things that the API can return with endpoints for barcodes, urls, providers, tracklists, and ISRCs. You can also pass an "&merge" parameter to let Harmony do its stitching together like it normally would.

At the moment, the Qobuz implementation is slightly higher priority but if we're stuck there for a little bit, I'll submit a PR for this API.

[ligeia]

No response from Qobuz yet so PR for API submitted: #190

[ligeia]

Coming back to this with some questions stimulated in the PR. Looking for feedback on what everyone values in an API.

To me, the most valuable function of the API would be to receive a given url and return the information about that release from that specific provider url. This could be one kind of lookup, e.g. /lookup?url=&full (pulls that provider's full details for the url) or /lookup?url=&full&merge (merges and returns full response).

The second most valuable is to pass a GTIN and receive back a merged response, e.g. /lookup?gtin=&full&merge.

Then we can add passing additional parameters instead of full. Here are some proposed parameters I tried to break into sections (we could start with just the categories as filters instead of initially adding all these different parameters):

1. Release Info - Release Name, Release Artists, Track Count, GTIN, Label, Release Date, Availability, Providers & Provider urls
2. Track Info - Track titles, Track Artists, Track Lengths, ISRCs, Providers & Provider urls
3. Artist Info - Release Artist, Release Artist urls, Track Artist, Track Artist urls
4. Cover art - Release cover art

so example query would be /lookup?url=api.provider.com/album/id&merge&release&track or /lookup?gtin=123457890&merge&track or /lookup?gtin=123457890&merge&artist and so on

@kellnerd raised what I think is an important point about having to balance what we're asking for with the fact that we're using an API to hit other APIs. Always starting from a full merged response and then filtering the returned JSON given certain parameters is using Harmony for what it's designed for, but it also means users may be hitting Harmony for more information than they actually need. On the other hand, if we make things too atomized, we are raising the question of why we're using Harmony to hit other APIs and only return what those APIs would individually return anyway.

But I should be careful about designing this in isolation. It's also possible that I'm too confident and missing some important considerations.

I'm open to hearing what people would value the most from the API before I attempt to submit a PR again.

[RustyNova016]

Personally what I'd like from a Harmony api is url/upc goes in, data that is supposed to be inserted as a release goes out.

My use case is simple: I got an app that takes MB data, check for discrepancies (No UPC on a Spotify release, missing track urls, etc... for exemple), and warn the user. I'd like to be able to ping harmony to ask "Hey I got a missing upc for url. Tell me what is it" so I can display it directly without having to make the user go to harmony.

That's the gist of it. Of course I'll cache the results to prevent duplicate requests, this mean doing like I do with the MB api and fetch everything at once. Been doing something similar with sambl data and so far it's working fine.