Add endpoint for service status

[buske]

Currently, the API has a single endpoint: .../match. I propose adding a new, public, endpoint, e.g. .../status whereby each system reports the status and configuration of that endpoint. I think this is very important for the scalability of this system.

Specifically, it would report any public data and dynamic attributes about that endpoint in a way that other MME services can consume. These could potentially include:

• Whether the system is online or not (based on whether it responds)
• The proper and display names of the organization, contacts, and any other public data the service is willing to disclose (e.g. # of patient records, optionally of course)
• The disclaimer to be displayed alongside results from that system
• The supported versions of the API
• The matching algorithms currently supported (Allow endpoint to support multiple matching algorithm(s) #115)
• A formal description of the data supported by that endpoint (e.g. genes? phenotypes? variants? these ontologies but not these? etc.)

Having this data be available as the response to a query to a non-authenticated endpoint allows other services and interested parties to see the extent of the network and what data is supported before going through the process of negotiating a key exchange.

[fschiettecatte]

I don't see how this helps scalability, but it goes some way to help discoverability and service selection for search.

[Relequestual]

I agree this could be interesting, but I'm not sure of the immediate utility, other than current availability. I think we should put this on ice till a few more databases are connected, as we might then better understand our needs.

[fschiettecatte]

How about this as 'heartbeat' endpoint under "/heartbeat":

{
    "heartbeat": {
        "production": true,
        "version": "software release version",
        "accept": ["application/vnd.ga4gh.matchmaker.v1.0+json", "application/vnd.ga4gh.matchmaker.v1.5+json"]
    }
}

[Relequestual]

Looks fine to me. However do we need a status property?
I would assume if it's a 200 status, it's alive, otherwise it's down.

[fschiettecatte]

Fine, updated in the comment.

[Relequestual]

I er meant the resulting HTTP status code of the request to the heartbeat endpoint.

[fschiettecatte]

Sure, that's kinda implied I think given HTTP

[Relequestual]

Right. So I see no reason to include "status": "up|down", in the endpoint json

[fschiettecatte]

Good point, gone.

[harindra-a]

looking great guys! For one fine day, probably not the first release, should we also have a field that gives back a "throughput" of a node. For example, the time taken to return a result to a query in milliseconds. Or would that be redundant and should be calculated locally?

[Relequestual]

@harindra-a looks like a MVP set to me... =/

I'm not really sure what use a "throughput" calcualtion would be. It's totally different based on the data given. It has no meaning at all.

[harindra-a]

I was thinking an average, given most requests coming in are fairly consistent, and automated answers/matches sent back can be timed. As a network grows, it can be a proxy for efficiency of the network as a whole. Anyway, your point is valid, and this is definitely not needed for now. Scratch it

[Relequestual]

I've seen a huge difference in time required for requests that contain only phenotypic data and no genes (which is perfectly legal). These types of requests can take a LOT longer depending on phenotypes.
In addition, we see a sizeable difference in speed depending on which genes are given, as we have a lot more variants for some genes vs others, which then all need to be scored before returning.

[fschiettecatte]

Following the Baltimore MME meeting, this was formalized and accepted for 1.1

[harindra-a]

yes, nice work everybody!

[Relequestual]

Pull request required.
Did we formalise this in a google doc?

[fschiettecatte]

I created branch for it adding a heartbeat-api.md file, see https://github.com/ga4gh/mme-apis/tree/issue-116 . I tend to be pretty brief when it comes to specs, please review and updated as needed. I will generate a pull request for it next week.