Discovering services and the use of profiles

It would be good to add a full end to end example using a profile. I suspect in the find function the profile(s) are meant to be URL(s) – IDs of the profiles, is that correct?

What would be another way to find a service in a landscape? I see the Heroku example has a field tags but that is not defined anywhere in the docs.

The full end-to-end client example should convey the following:

How do I discovery the registry in the first place?
Given I want to find and use a UUID-generating service in my landscape by a profile (I have profile ID–URL) how do I proceed?
Given I've found a service which conforms to UUID-generating profile, how am I going to find how to actually use it – meaning how am I going to discover what endpoint of that service should I call with what parameters, and how to handle the response.

I understand, the last point is out out the DISCO scope itself but I am strongly convinced that a complete example from the client perspective is critical. We shouldn't be just saying A without B...

right -- good stuff here.

1) you MUST know a registry exists to start (there is no -- as yet -- registry of registries). i suspect an additional operation in the registry spec might be "list-of-registries" as a way of asking a registry if it knows of any other registries. this is a meta spec we can put off for a while, IMO.

2) you SHOULD be able to query a registry to find what you are looking for. this can be done a few ways. for example, i might ask the registry to list all entries that has a cretain ALPS profile URI ("give me a list of services that support http://alps.org/profiles/uuid-generator/v1"). i might ask the registry for all entries that are tagged with "#UUID", etc.

3) there MAY be some "handshaking" that needs to go on between the the time i FIND a service to use and when I can then use it. for example, i might need to get an usage token (think API key), i might need to agree to terms, send a shared key (like an oauth bearer token exchange), or even engage in some bidding on usasge/price (think ad networks). again, there MAY NOT be anything needed at all.

Once all handshaking is out of the way, i MAY need to make an initial request to a "start" endpoint that is in the registry entry (i am vague on this since i've not experimented enough here). that reply SHOULD look like something that is already described in the profile (ALPS or other) and that SHOULD be enough for my client to then take over.

For example, upon by BIND action, i get a response from the registry that includes an API key token and one or more URLs marked with the IDs from an ALPS profile:

{"collection" : 
  {
    "api-key" : "q1w2e3r4t5y6u7",
    "links" : [
      {"id" : "home", "href" : "..."},
      {"id" : "start-session", "href" : "..."},
      {"id" : "end-session", "href" : "..."},
      {"id" : "documentation", "href" : "..."},
      {"id" : "profile", "href" : "..."}
    ]
  }
}

and, yes, a fully working example of this (at least one, SHOULD be more) is needed.

you MUST know a registry exists to start (there is no -- as yet -- registry of registries). i suspect an additional operation in the registry spec might be "list-of-registries" as a way of asking a registry if it knows of any other registries. this is a meta spec we can put off for a while, IMO.

Couldn't a registry service, just like any other service, have some profile like http://alps.org/profiles/disco-registry/v1? That way one could crawl registries easily.

I might ask the registry for all entries that are tagged with "#UUID", etc.

So what is up about the tags, there are not in the DISCO spec (and I am not yet convinced they should be). But I recognize the main challenge with DISCO is really how to declare what a registered service offers, maybe tags can help with interfacing to humans.

Which brings me to the point "DISCO is for Services, Not Machines" – is it also for humans, or is it meant purely for machines?

there MAY be some "handshaking" that needs to go on between the the time i FIND a service to use and when I can then use it. for example, i might need to get an usage token (think API key), i might need to agree to terms, send a shared key (like an oauth bearer token exchange), or even engage in some bidding on usasge/price (think ad networks). again, there MAY NOT be anything needed at all.

Ok so this is a whole big bucket to be figured out but this is still just a prequel to the challenge of how to make the endpoints from the bound service usable. Hypermedia would be, of course, a way to do it but how about, for example, mapping ALPS profiles to OAS (swagger) documents (or the other way around)?

I like the bind function example that returns the mapping from profile to hrefs...

I would like to work on those examples.

Couldn't a registry service, just like any other service, have some profile like http://alps.org/profiles/disco-registry/v1? That way one could crawl registries easily.

well labeling (e.g. emiting a profile header) and actually finding all the servers on the internet that emit that label (e.g. crawling) are wildly differnt things.

i'm open to exploring this. the ability to "find more registries" is important in the long run. but -- just like humans -- bots will need a starting point (some web address that is the equivalent of a search engine) and that why i say bots MUST have at least one known registry to start with.

or am i kinda missing the point here?

Hypermedia would be, of course, a way to do it but how about, for example, mapping ALPS profiles to OAS (swagger) documents (or the other way around)?

yes, using hypermedia is a super-simple way to make it possible for bots to "recognize" ids and names and then act on them as expected. that's the point of ALPS, BTW. to collect all the properties and action names that a bot should be ready to "see".

as for OAS, AsynAPI, GraphQL's SDL, protobuff, etc. these are all great API definition documents for a single server somewhere out there. We don't need a mapping to the definitions in the registry but we sure can have the associations. one way i considered doing this is using Kin Lane's APIs.json to hold all that stuff. IOW, a field in he DISCO spec that points to an APIs.json (one loaded by the service when it registers) and then that contains information about SLA, endpoints, doc URLs, etc.)

this is me pushing the details off on another spec/doc. again, late binding to it for now. if we find that some of these values need to e native to the DISCO spec, we can safely add them later in a backward compatible way, right?

So what is up about the tags, there are not in the DISCO spec (and I am not yet convinced they should be).

yeah - tags got added after i started to implement the first examples. i want some unstructured field that allows folks to load up strings (like the "class=" in HTML) for narrowing search. the "tags" field is left out of the spec -- that's a bug.

eventually, we may find some structured fields make sense, too (category, owner, rating, quality, etc.) but i didn't want to overspec things at the start. we'd be able to safely add those features as non-breaking changes in the future when needed.

does that help?

I would like to work on those examples.

music to my ears!

well labeling (e.g. emiting a profile header) and actually finding all the servers on the internet that emit that label (e.g. crawling) are wildly differnt things.

i'm open to exploring this. the ability to "find more registries" is important in the long run. but -- just like humans -- bots will need a starting point (some web address that is the equivalent of a search engine) and that why i say bots MUST have at least one known registry to start with.

or am i kinda missing the point here?

I think I was not clear, I understand there must be one registry service known to a client to start with. I was more thinking about other "registry services registering to registry services" creating registry meshes so to speak.

I think the only thing we really need for this at the moment is the "registry profile" and requirement that an implementation of a DISCO registry service conforms to this profile.

as for OAS, AsynAPI, GraphQL's SDL, protobuff, etc. these are all great API definition documents for a single server somewhere out there. We don't need a mapping to the definitions in the registry but we sure can have the associations. one way i considered doing this is using Kin Lane's APIs.json to hold all that stuff. IOW, a field in he DISCO spec that points to an APIs.json (one loaded by the service when it registers) and then that contains information about SLA, endpoints, doc URLs, etc.)

this is me pushing the details off on another spec/doc. again, late binding to it for now. if we find that some of these values need to e native to the DISCO spec, we can safely add them later in a backward compatible way, right?

100% agree we should not have the mapping in the registry to the API definition formats.

My point is, for non-hypermedia API machine to machine communication that does not involve humans reading any documentations (besides programing the user agent for profile) there has to be mapping from the profile to to the actual interface invocations (e.g. to HTTP requests). Now I recognize these are out of the scope of DISCO but in order to provide a meaningful end-to-end example of such a machine to machine discovery and communication we need to figure it out, maybe as part of ALPS or another project but still we should give that example...

yeah - tags got added after i started to implement the first examples. i want some unstructured field that allows folks to load up strings (like the "class=" in HTML) for narrowing search. the "tags" field is left out of the spec -- that's a bug.

OK on tags.

webapicookbook / registry-docs

Discovering services and the use of profiles #4