Looking for solutions: Web Service discovery and description

[Paul Frazee]

I'm looking for a good standard to "describe and discover" Web services in Beaker. Any opinions out there?

Why: Beaker is going to maintain a registry of services for the user, which apps can query for endpoints.

// for example...
var url = await serviceRegistry.getPreferred('search')
var results = await fetch(url + '?q="beaker browser"')

For this to work, Web Services need a good way to describe themselves. It doesn't need to be extremely detailed; just enough to identify behaviors. The Link response-headers, for instance, are not bad.

I want to make an informed decision, so I've done some cursory research on existing specs. Here's what I've found so far:

• WebFinger is very lightweight but defunct. It has the image of being purely for user-lookup, but it can actually be used for services generally. It's not far from what I have in mind.
• WSDL is overly-specified. It tries to describe the APIs, when we need something more like protocol or relation labels. We don't need that level of detail, because we're not generating code from the descriptions.
• CalDav/CardDav has discovery but it looks too simple; it's just a .well-known endpoint that redirects to the cal/card-dav endpoint.

Appreciate the help.

-prf

[Morgaine Fowle]

I'm not sure what kind of content you'd want to convey, but I'd start with RFC 5785 Defining Well-Known Uniform Resource Identifiers[1] (which defines /.well-known/), and perhaps move on to RFC 6415 Web Host Metadata[2] (which defines host-meta.json, providing a set of links).

RFC 6415 isn't all that popular, but it's job is simple enough- provide a list of links to resource types. Each kind of service ("search") probably *should* in any decent web-y spec have a IANA Media Type/MIME Type, and RFC 6415 is a direct way to enumerate all services by their MIME type. Specifically look to the JRD section for the JSON form. This is suitable if all you want is a media-type (here, the media being perhaps a service of a certain type) and a URL to start talking to that media type.

OpenAPI is around but I'm not aware of any facility for example for Alice and Bob to both advertise that they have implementations up of Chad's Search Service interface. It seems more catered to describing the shape of your own API, but free from external context. I could be off base here, and if so, OpenAPI would make a great choice simply because it has wide-spread adoption.

Last, there's a bunch of different ways one could discover an EntryPoint[3]. Since it's JSON-LD, one can embed EntryPoint data-islands or microdata onto any HTML page, identifying potentialActions that are available at that point. There's already a strong set of common well known actions that pages can offer, from ViewAction to ShareAction & anyone wanting to create new action types has only to define a namespace for their actions.

[1] https://tools.ietf.org/html/rfc5785
[2] https://tools.ietf.org/html/rfc6415
[4] https://schema.org/EntryPoint

[Paul Frazee]

I had seen host-meta. I'll give that a deeper look, as well as JSONLD.

You're right about Swagger. It's a much better take on WSDLs. It doesnt do what I need but it might have a place in Beaker, sometime in the future.

--
You received this message because you are subscribed to the Google Groups "Beaker Browser" group.
To unsubscribe from this group and stop receiving emails from it, send an email to beaker-browser+unsubscribe@googlegroups.com.
To post to this group, send email to beaker-browser@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/beaker-browser/c1169f29-e1a3-4c41-8c9b-07333bb6b578%40googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

[Francis Meetze]

What you've done here Paul is fascinating and this is the only piece missing.

To unsubscribe from this group and stop receiving emails from it, send an email to beaker-browse...@googlegroups.com.
To post to this group, send email to beaker-...@googlegroups.com.

[Michael Sullivan]

I'd go with swagger.json or openapi.json

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#file-structure

Previously:

https://github.com/OAI/OpenAPI-Specification/wiki#server

On Monday, January 2, 2017 at 8:22:16 PM UTC-5, Paul Frazee wrote: