Service discovery

[chriskapp]

Hi, in this thread I would like to talk about service discovery for REST APIs. At our api management system we return at the root / endpoint a response pointing out several standard endpoints, in the following a sample response:

{
    "apiVersion": "6.0.0.0-RC4",
    "title": "Fusio",
    "categories": [
        "authorization",
        "system",
        "consumer",
        "backend",
        "default"
    ],
    "scopes": [
        "default"
    ],
    "apps": {
        "developer": "http:\/\/api.fusio.cloud:8080\/apps\/developer",
        "documentation": "http:\/\/api.fusio.cloud:8080\/apps\/documentation",
        "fusio": "http:\/\/api.fusio.cloud:8080\/apps\/fusio",
        "swagger-ui": "http:\/\/api.fusio.cloud:8080\/apps\/swagger-ui"
    },
    "links": [
        {
            "rel": "root",
            "href": "http:\/\/api.fusio.cloud:8080\/"
        },
        {
            "rel": "openapi",
            "href": "http:\/\/api.fusio.cloud:8080\/system\/export\/openapi\/*\/*"
        },
        {
            "rel": "documentation",
            "href": "http:\/\/api.fusio.cloud:8080\/system\/doc"
        },
        {
            "rel": "route",
            "href": "http:\/\/api.fusio.cloud:8080\/system\/route"
        },
        {
            "rel": "health",
            "href": "http:\/\/api.fusio.cloud:8080\/system\/health"
        },
        {
            "rel": "jsonrpc",
            "href": "http:\/\/api.fusio.cloud:8080\/system\/jsonrpc"
        },
        {
            "rel": "oauth2",
            "href": "http:\/\/api.fusio.cloud:8080\/authorization\/token"
        },
        {
            "rel": "whoami",
            "href": "http:\/\/api.fusio.cloud:8080\/authorization\/whoami"
        },
        {
            "rel": "about",
            "href": "https:\/\/www.fusio-project.org"
        }
    ]
}

We use these "links" at other apps to discover those endpoints.

In the end I think it would be really great if there was a standard to describe our API and which technologies are used. I.e. in the links section we have a rel "oauth2" which points to an OAuth2 token endpoint and a rel "jsonrpc" which points to an JsonRPC endpoint. With such a standard integrating an API could be also a lot easier since a user could simply provide at some service the base url and the system can automatically discover what services are available at the API.

So this problem is not new and I am aware of the webfinger spec which also tries to provide some sort of service discovery but it is more related to a specific resource. Then I am following also on this group the linkset spec which looks promising and which could be also used for service discovery. Are there also other specifications available which try to solve this problem?

The great thing of such a response at the root endpoint is also that developers can read this response and they directly get information about specific endpoints. In general I think the biggest problem (and probably also greatest strength) of REST is the lack of standardization since every endpoint can return a complete custom response and there is no way that such a response can be understood by a generic system. Currently our industry has tried to solve this either by creating a hard spec like JSON:API or OData or to follow more the HATEOAS route. I think both ways are great and there will be never one global standard which is used by everyone and this also not the nature of the web.

So I think the best solution is to simply describe the form of specific endpoints, so that also generic tools can better understand an API. Then we could also standardize specific responses i.e. for health checks etc. and we can also describe specific standards saying i.e. that theses routes are following JSON:API, OData etc. thus we are not forced to create one global specification but every API could implement the specs which are useful for its specific case. So please let me know your thoughts and also pointers to specs which I am not aware of.

[asbjornu]

Atom has Service Documents, Hydra has the ApiDocumentation resource and @mnot's been working on Home Documents for HTTP APIs. I'm sure most hypermedia formats have something similar.

[darrelmiller]

There is also the api.json effort http://apisjson.org/ There is definitely a lot of interest in this area. Just never quite enough traction.

[chriskapp]

Thanks for the pointers. I was not aware of apisjson but it looks really useful, unfortunately that it has not gained more traction.

[dret]

Should we bring this to the mailing list? It's not quite clear how much visibility the GitHub discussions are getting.

[richsalz]

Bringing it to the email list is always appropriate.

[darrelmiller]

There is an effort over in the CloudEvents world for defining a registry that would enable discover of things such as APIs https://github.com/cloudevents/spec/blob/main/registry/spec.md

[dret]

On 2023-03-26 20:35, Darrel wrote: There is an effort over in the CloudEvents world for defining a registry that would enable discover of things such as APIs https://github.com/cloudevents/spec/blob/main/registry/spec.md

interesting. in terms of "categorizing" APIs in some way, have you seen this effort being aligned with schema.org in any way? and to be honest, i lost track a little how much and what schema.org did for APIs, but i do remember that for a little while, there was some interest in adding APIs to the things that can be described with schema.org.

…

-- Erik Wilde | ***@***.*** | | https://youtube.com/ErikWilde |