[bug] /api/v1/instance, `uri` property is a URI, instead of a bare domain

nikclayton commented

2025-05-05 09:25:13 +00:00

Your setup

From source

Extra details

No response

Version

3.15.1-0-g7eec493

PostgreSQL version

No response

What were you trying to do?

At the /api/v1/instance endpoint the uri property (despite the name) is supposed to be just the domain of the server (https://docs.joinmastodon.org/entities/V1_Instance/#uri). No leading protocol, ports, etc.
Spot-checking Mastodon API compatible servers shows this is the case for at least Pixelfed, Pleroma, Fedibird, Friendica, Iceshrimp.

Akkoma doesn't -- e.g., https://genserver.social/api/v1/instance, version "2.7.2 (compatible; Akkoma 3.15.1-0-g7eec493)", exposes the uri property as "https://genserver.social" instead of the correct "genserver.social".

What did you expect to happen?

No response

What actually happened?

No response

Logs

No response

Severity

No response

Have you searched for this issue?

I have double-checked and have not found this issue mentioned anywhere.

### Your setup From source ### Extra details _No response_ ### Version 3.15.1-0-g7eec493 ### PostgreSQL version _No response_ ### What were you trying to do? At the /api/v1/instance endpoint the `uri` property (despite the name) is supposed to be just the domain of the server (https://docs.joinmastodon.org/entities/V1_Instance/#uri). No leading protocol, ports, etc. Spot-checking Mastodon API compatible servers shows this is the case for at least Pixelfed, Pleroma, Fedibird, Friendica, Iceshrimp. Akkoma doesn't -- e.g., https://genserver.social/api/v1/instance, version "2.7.2 (compatible; Akkoma 3.15.1-0-g7eec493)", exposes the `uri` property as `"https://genserver.social"` instead of the correct `"genserver.social"`. ### What did you expect to happen? _No response_ ### What actually happened? _No response_ ### Logs _No response_ ### Severity _No response_ ### Have you searched for this issue? - [x] I have double-checked and have not found this issue mentioned anywhere.

nikclayton added the

bug

label 2025-05-05 09:25:13 +00:00

floatingghost commented

2025-05-05 15:11:29 +00:00

Owner

what is the impact of this? including the protocol is more "correct" for a uri field imo, does including it cause any issues?

nikclayton commented

2025-05-05 18:24:49 +00:00

Author

The impact is that clients that attempt to parse this property as a domain -- which, despite the name of the property, it is -- will fail to parse it, because the value is a URL.

From a client's perspective this is a non-recoverable error -- the server is returning bogus data, and trying to guess the server's intention is just as likely to result in more errors.

https://docs.joinmastodon.org/entities/V1_Instance/#uri is clear this is a domain, the description says "The domain name of the instance"

Other text properties in the v1 instance response that are URLs are explicitly called out as such in the documentation (e.g., thumbnail (https://docs.joinmastodon.org/entities/V1_Instance/#thumbnail)).

The Mastodon devs corrected the confusing property name in api/v2/instance, where the property is now called domain (https://docs.joinmastodon.org/entities/Instance/#domain). Their intent is clear, as the description for the url property in V1 and the domain property in V2 are identical.

The impact is that clients that attempt to parse this property as a domain -- which, despite the name of the property, it is -- will fail to parse it, because the value is a URL. From a client's perspective this is a non-recoverable error -- the server is returning bogus data, and trying to guess the server's intention is just as likely to result in more errors. https://docs.joinmastodon.org/entities/V1_Instance/#uri is clear this is a domain, the description says "The domain name of the instance" Other text properties in the v1 instance response that **are** URLs are explicitly called out as such in the documentation (e.g., `thumbnail` (https://docs.joinmastodon.org/entities/V1_Instance/#thumbnail)). The Mastodon devs corrected the confusing property name in api/v2/instance, where the property is now called `domain` (https://docs.joinmastodon.org/entities/Instance/#domain). Their intent is clear, as the description for the `url` property in V1 and the `domain` property in V2 are **identical**.

floatingghost commented

2025-05-05 18:26:36 +00:00

Owner

I guess I should rephrase the question - do there exist clients which fail on this specific deviation?

it's hard to imagine a scenario in which you'd fetch this URL and not already know the instance domain name

I guess I should rephrase the question - do there exist clients which fail on this specific deviation? it's hard to imagine a scenario in which you'd fetch this URL and not already know the instance domain name

nikclayton commented

2025-05-05 18:33:49 +00:00

Author

Irrelevant.

You can't just pick and choose which bits of the API spec you want to follow, and stuff random data in other properties and hope that clients will figure it out.

For example, Mastodon status IDs look like numbers, but are strings. You would not be following the Mastodon spec if you returned those IDs as JSON numbers instead of strings, however much you think they look like numbers.

Irrelevant. **You can't just pick and choose which bits of the API spec you want to follow, and stuff random data in other properties and hope that clients will figure it out.** For example, Mastodon status IDs look like numbers, but are strings. You would not be following the Mastodon spec if you returned those IDs as JSON numbers instead of strings, **however much you think they look like numbers**.

floatingghost commented

2025-05-05 18:39:08 +00:00

Owner

it's actually very relevent! it's not common knowledge, but the entire activitypub spec and everything built on top is actually very up for interpretation. in fact, mastodon don't even have an API specification, it's a living document of how it behaves in the current moment

every piece of software actually does things slightly differently, and whilst not ideal, everyone does in fact pick and choose which parts to implement

point sorta being that we'd think more about if a "fix" was justified based on of anyone cared what the field is

it's actually very relevent! it's not common knowledge, but the entire activitypub spec and everything built on top is actually very up for interpretation. in fact, mastodon don't even have an API specification, it's a living document of how it behaves in the current moment every piece of software actually does things slightly differently, and whilst not ideal, everyone does in fact pick and choose which parts to implement point sorta being that we'd think more about if a "fix" was justified based on of anyone cared what the field is

nikclayton commented

2025-05-05 18:45:55 +00:00

Author

actually very up for interpretation

"The domain name of the instance." (https://docs.joinmastodon.org/entities/V1_Instance/#uri) is crystal clear.

I know that Pachli (and by inheritance, Tusky) have code that is more complicated than it needs to be to work around this Akkoma bug. It was in the course of trying to simplify this code to follow the spec that I discovered Akkoma is not compliant.

> actually very up for interpretation "The domain name of the instance." (https://docs.joinmastodon.org/entities/V1_Instance/#uri) is crystal clear. I know that Pachli (and by inheritance, Tusky) have code that is more complicated than it needs to be to work around this Akkoma bug. It was in the course of trying to simplify this code to follow the spec that I discovered Akkoma is not compliant.

floatingghost commented

2025-05-05 18:49:10 +00:00

Owner

so, to clarify:

does there exist a client that fails on this deviation?

could have been more easily answered with

yes, I'm trying to parse things and having to work around this

it's much harder to prioritise what needs doing if the impact of things isn't made clear!

so, to clarify: >does there exist a client that fails on this deviation? could have been more easily answered with >yes, I'm trying to parse things and having to work around this it's much harder to prioritise what needs doing if the impact of things isn't made clear!

nikclayton referenced this issue from a pull request that will close it,

2025-05-06 09:23:16 +00:00

fix: Return the webfinger host as the instancev1 uri property #908

~~nikclayton referenced this issue 2025-05-06 20:00:16 +00:00~~

fix: Return the webfinger host as the instancev1 uri property #908