OpenAPI Questions

[grippy]

I've finished reading the current specification and I'm up-to-date with the proposed OAuth changes.

While I realize this specification is still incubating, I'm sort of thinking long term a little bit about adoption. For example, I'm looking at making a Search/Discovery App. And I see the stubbed out discovery folder in this repo. Let's use this as an example.

Is the current thinking that we'll have a single, versioned specification that describes the API for calling into a Discovery-type application? I think this would be ideal if we could agree on some generalized spec around this. This would also make it much easier to implement from the Fediverse Server-side if there was a single Discovery API vs. each application defining its own. Then if this generalized spec doesn't meet your criteria you can publish your own variation or propose changes to it, etc.

With this in mind, would it be beneficial to model API response types using ActivityStream types? Don't recall seeing anything around how best to model request/response types.

The way the application versioning is currently structured it seems like the intention is that an application is only a single type of thing and version. Is this correct? Or, is it possible my application could handle integrations for any number of types? (I'm using type to mean Discovery, Link Preview, Spam Detection, Debug, etc). I think it would be ideal if the provider_info allowed the version to be a list of objects. And then to support multiple types and versions within the same application, we would need to prefix all api routes with something like this: /spec/{id}/v{version}/....

[oneiros]

While I realize this specification is still incubating, I'm sort of thinking long term a little bit about adoption. For example, I'm looking at making a Search/Discovery App. And I see the stubbed out discovery folder in this repo. Let's use this as an example.

For a less empty version of that folder you might have a sneak peek at the https://github.com/mastodon/fediverse_auxiliary_service_provider_specifications/tree/discovery_basics branch. Note that this is heavily wip though.

Is the current thinking that we'll have a single, versioned specification that describes the API for calling into a Discovery-type application?

Yes.

I think this would be ideal if we could agree on some generalized spec around this. This would also make it much easier to implement from the Fediverse Server-side if there was a single Discovery API vs. each application defining its own. Then if this generalized spec doesn't meet your criteria you can publish your own variation or propose changes to it, etc.

Exactly.

With this in mind, would it be beneficial to model API response types using ActivityStream types? Don't recall seeing anything around how best to model request/response types.

Maybe? Initially I had expected we could (re)use a lot more of AP/AS, but so far this has not panned out. We are however not yet at the point where we can specify what exactly the result of a "search" (whatever that is) is. So I would not yet rule it out.

The way the application versioning is currently structured it seems like the intention is that an application is only a single type of thing and version. Is this correct? Or, is it possible my application could handle integrations for any number of types? (I'm using type to mean Discovery, Link Preview, Spam Detection, Debug, etc).

If your application is a FASP it might in fact implement any number of specifications and capabilities defined therein. So a "super fasp" trying to do everything is possible, but so is a "small" discovery fasp that only computes trends.

I think it would be ideal if the provider_info allowed the version to be a list of objects.

It does! But this is per capability, so a FASP might support v1.0 of computing "trends" but v2.0 of "account_search".

And then to support multiple types and versions within the same application, we would need to prefix all api routes with something like this: /spec/{id}/v{version}/....

Yes, probably. For some reason we (I?) did not want this, at least not initially. But I cannot remember why ☹️

I will get back to this once we finalize the new auth stuff.

[oneiros]

I think it would be ideal if the provider_info allowed the version to be a list of objects.

It does! But this is per capability, so a FASP might support v1.0 of computing "trends" but v2.0 of "account_search".

Sorry, I misread your point. With the current draft it would have to be:

{
  "capabilities": [
    {
      "name": "trends",
      "version": "1.0"
    },
    {
      "name": "trends",
      "version": "2.0"
    }
  ]
}

which is more verbose than

{
  "capabilities": [
    {
      "name": "trends",
      "versions": ["1.0", "2.0"]
    }
  ]
}

I will think about this some more.