Expose some description of functionality supported by the instance in the API

[ekiru]

As we begin to add new API-exposed functionality (new endpoints/new fields/new params/new stuff/etc.) it'd be useful for clients to be able to ask the server which functionality it supports so that other clients would be able to start incorporating support for that functionality in a reliable fashion.

There are two obvious approaches I can think of, both of which involve codifying identifiers of some kind for each extension:

1. Expose a /api/v1/extensions (or capabilities or features or some other name) which returns a list of extensions (and optionally additional fields with metadata about particular extensions, but that's really up to the particular extension).
2. Expose a "extensions" or "supports-extensions" field on the /api/v1/instance (and optionally additional fields with metadata about particular extensions, but that's really up to the particular extension).

So the two big questions I have with this are:

1. how to refer to and define/specify/codify/whatever extensions
2. separate endpoint or not

I am leaning towards preferring not a separate endpoint myself for 2.

For 1, I think probably the best way would be to write up a specification of each feature we want to expose like this, talking about what it does, API-facing/user-facing/other-server-facing aspects of how it works, recommendations for how it should be exposed/used in clients if appropriate, etc. and assign a URI as the identifier used in the extensions (ideally the URI would itself just point to the spec). A lot of the protocols that OStatus (and eventually ActivityPub as well I think) involves use a similar approach of URIs for identifiers, and it also has the advantage of naturally namespacing different organizations' extensions: if, for example, pawoo decided to implement custom emoji one way, while glitch-soc decided to do it another way, you'd probably end up with http://spec.glitch.social/custom-emoji and http://pawoo.net/specs/custom-emoji or something like that. In contrast simple string identifiers would be more likely to collide if we just went around calling it "custom-emoji".

We'd want to write up a spec for the supports-extensions field or whatever we decided upon to start things off, in this approach. :)

---

• I searched or browsed the repo’s other issues to ensure this is not a duplicate.

[ghost]

this is probably part of the activitypub thing if i recall the name correctly. garg tooted about it, let me check

[nightpool]

the current plans for AP don't affect the mastodon API (client<->server stuff), so that part of this is at least relevant. AP is very easy to implement extensions for, and the JSON-LD contexts make it clear which type of things your document includes, and implementing stuff is easy to do in a backwards compatible way, so server-server stuff is probably less relevant here.

…

On Sun, Aug 6, 2017 at 2:18 PM Surinna Curtis ***@***.***> wrote: As we begin to add new API-exposed functionality (new endpoints/new fields/new params/new stuff/etc.) it'd be useful for clients to be able to ask the server which functionality it supports so that other clients would be able to start incorporating support for that functionality in a reliable fashion. There are two obvious approaches I can think of, both of which involve codifying identifiers of some kind for each extension: 1. Expose a /api/v1/extensions (or capabilities or features or some other name) which returns a list of extensions (and optionally additional fields with metadata about particular extensions, but that's really up to the particular extension). 2. Expose a "extensions" or "supports-extensions" field on the /api/v1/instance (and optionally additional fields with metadata about particular extensions, but that's really up to the particular extension). So the two big questions I have with this are: 1. how to refer to and define/specify/codify/whatever extensions 2. separate endpoint or not I am leaning towards preferring not a separate endpoint myself for 2. For 1, I think probably the best way would be to write up a specification of each feature we want to expose like this, talking about what it does, API-facing/user-facing/other-server-facing aspects of how it works, recommendations for how it should be exposed/used in clients if appropriate, etc. and assign a URI as the identifier used in the extensions (ideally the URI would itself just point to the spec). A lot of the protocols that OStatus (and eventually ActivityPub as well I think) involves use a similar approach of URIs for identifiers, and it also has the advantage of naturally namespacing different organizations' extensions: if, for example, pawoo decided to implement custom emoji one way, while glitch-soc decided to do it another way, you'd probably end up with http://spec.glitch.social/custom-emoji and http://pawoo.net/specs/custom-emoji or something like that. In contrast simple string identifiers would be more likely to collide if we just went around calling it "custom-emoji". We'd want to write up a spec for the supports-extensions field or whatever we decided upon to start things off, in this approach. :) ------------------------------ - I searched or browsed the repo’s other issues to ensure this is not a duplicate. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#123>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAORVy4OO0Us1mR8n3C9yTNgRSZDdm95ks5sVgNZgaJpZM4OuzSR> .

[ghost]

im not 100% sure i understand yr post @nightpool (thats okay im not super technical) but the important thing to note imo is activity pub (as far as i understand it) supports having servers talk to each other and ask questions similar to 'can you do this?' or 'do you support this feature?' to allow for us to have ours at least use this sort of stuff to do extensions easily / in spec with upstream work. my understanding is they already have activity pub MOSTLY implemented up stream so we can probably slot it into existing code

[nightpool]

Ah, sorry, let me be clearer.

ActivityPub, as a spec, has two parts: The server <-> server interactions, and the server <-> client interactions. respectively, examples of these are mastodon.social talking to glitch.social, and mastodon.social talking to amaroq or twidere. Currently, gargron is implementing the first half, but we don't have any plans to implement the second half.

So extensions that affect the first half are fine to implement without doing anything special. Extensions that affect the second half might still want to be defined somewhere.

[ekiru]

@nightpool, that's useful to know, thanks!

It sounds like ActivityPub will handle at least some of the information about server-server interactions one might want to extend, though I'm not familiar enough with the details of how that extension works to be sure it would handle everything smoothly (for example, would it help with not sending, say, follower-only (or unrebloggable if we eventually separate that out) posts to instances that don't support that concept?), though I'd say it's probably still useful to clearly define any such extensions we introduce, either way, but we may not need to worry about a new way to expose what we support depending on how ActivityPub's approach works.

The client-server bit is what I'm most immediately interested in, though, so convenient to me that I don't quite yet have to read ActivityPub (although if you tell me that there's a standardized way in it to say "we support this extra API endpoint or API parameter or value for this API parameter or API response field with this defined meaning" I'll go read it anyway in order to consider learning from its example and to avoid gratuitous incompatibility with its approach...)