API Refactoring

[0xf0xx0]

Ahoy! uwu7

The API right now is a bit odd. Some endpoints return JSON, others return numbers, and other just strings. I feel it should all be JSON, to make it easier on languages and libraries that have a distinction. Some API methods could then be consolidated, reducing the number of requests needed. For example, /blocks/tip/hash and /blocks/tip/height could be merged into /blocks/tip returning both the header and the height in a JSON object.
Also, if the price api is disabled, would it be better to return a error instead of a empty
object?

[janoside]

I agree with most (maybe all) of these ideas. I'd like to address before the next release.

[0xf0xx0]

I can start a pr, just need to know your preferred style (and of course, read over the code more x3)

[janoside]

Thanks for the offer here. I had a lot that I needed to think through, and I tend to do that by just writing code. Happy to hear thoughts about this commit.

[pointbiz]

I think this makes sense. Some methods were modeled after other APIs in the wild. Like blockchain dot info or mempool dot space. So, there is a lack of consistency.

I do see the benefit of always returning a json especially for error handling.

Of course it will break existing integrations but users can time their upgrades.

[0xf0xx0]

maybe the relevant methods should be marked as deprecated in the next release, and change in the release after?

[janoside]

Yea, maybe. I may even want to introduce url-level versioning, ala /api/v2/.... Don't want to over-complicate, but also don't want to be too slow either. Going with url versioning I can just release, anyone can update without worrying about it, and update their urls when they see fit. So, with this approach step 1 is just copy/paste apiRouter to apiV2Router. Happy to hear objections from anyone weighing in here...

[janoside]

In this approach, all of v1 (current API) would be "marked deprecated".

[pointbiz]

I really like this approach you suggested. People will feel more confident to integrate because old api won't break right away.

[0xf0xx0]

Also, noticed /util/xyzpub/:extendedPubkey, /xyzpub/txids/:extendedPubkey, and /xyzpub/addresses/:extendedPubkey. Should they be flipped around to branch off of /xyzpub/:extendedPubkey (/xyzpub/:extendedPubkey/util, /xyzpub/:extendedPubkey/txids, and /xyzpub/:extendedPubkey/addresses)?

[janoside]

Yea, I think you're right. (I think I did this because of the unpleasant UX issue of very long xpub values which make seeing the end of the URLs impractical... so, I'm torn)

[pointbiz]

It's not a restful api so it's fine the xpub goes after to make usability easier

[janoside]

I've gone back and forth on the issue of including version numbers in API URLs, even moving forward with a candidate implementation. After this work, I've concluded AGAINST the URL-based versioning because I think it just adds too much complexity for a relatively simple, stable API. In line with semantic versioning, the API changes we're discussing here will still constitute a breaking, major version update to 2.x, but I think it's best for the URLs to remain unchanged. I'll try to ensure documentation for the next explorer update give clear guidance about the breaking changes.

[janoside]

Just committed a v2 of the API. Happy to hear any thoughts. 09a31f1

[0xf0xx0]

looks good to me :з

[pointbiz]

On second thought I agree with this approach because it's less maintenance in the code. And the API is somewhat new and after this nice clean up, it will be relatively stable. The semantic versioning and changelog warnings should be good enough.