search

facilityregistry / fred-api

Facility Registry API Documentation Website
11 stars 4 forks source link

How to expose metadata for a facility registry #57

Open steesdale opened 11 years ago

steesdale commented 11 years ago

How to expose metadata for a facility registry (fields, types, constraints, etc)

Why it matters: it would help client applications and systems understand the data available and do more transparent integrations. E.g. Commcare adds a form that lets a facility manager update the status of infrastructure in a facility.

ctford commented 11 years ago

I'm not sure I support trying to expose metadata in a machine-readable format WSDL-style. I don't really think that anyone would be trying to automate creating a client for the facility registry, and I don't think such an attempt would be likely to succeed.

I'm not sure I understand why the example of Commcare adding a form would have anything to do with the facility registry? Would the form not just be an out-of-band way of interacting with the system, and under-the-hood be translated into normal interactions with the FRED API?

However, it would make a lot of sense to allow a facilities registry to link to e.g. HTML format documentation.

edjez commented 11 years ago

Well, for starters that's exactly how the native API for the 'form designer' and the facility editor work in the native Resource Map UI. So that would count as a client. Your reference to WSDL makes me think the initial suggestion was misunderstood; did you really mean WSDL or more XSD? WSDL is more about the discoverability of API endpoints and their operations,bindings, behaviors etc. (of which document exchange schemas are just a part). That was not the intent, sorry.

I was trying to convey something more XSD-ish (i.e metadata like" A facility has a 'number of beds' integer, a 'source of electricity' field with options {NONE, GENERATOR,SOLAR, FUSION} etc )

Also having the entity metadata allows you to discover: What are the fields and their labels for a particular language? If you are entering facility data element which denominates "Ownership" (Or "Power Source" or ..) and it's a coded variable, what are the potential codes? If facilities have a field which is a hierarchical data element, what is the hierarchy of options available?

Without this information it is not possible to make any clients of the service that are not hardcoded.

On May 27, 2013, at 1:17 AM, Chris Ford notifications@github.com wrote:

I'm not sure I support trying to expose metadata in a machine-readable format WSDL-style. I don't really think that anyone would be trying to automate creating a client for the facility registry, and I don't think such an attempt would be likely to succeed.

I'm not sure I understand why the example of Commcare adding a form would have anything to do with the facility registry? Would the form not just be an out-of-band way of interacting with the system, and under-the-hood be translated into normal interactions with the FRED API?

However, it would make a lot of sense to allow a facilities registry to link to e.g. HTML format documentation.

— Reply to this email directly or view it on GitHub.

ctford commented 11 years ago

I think I was confused about who was making the discovery, a human or a machine. My reference to WSDL was because I'd read @steesdale's original comment as being about automated discovery.

Wouldn't an HTML documentation of the API be a good way of describing potential codes etc? Do you imagine a format that's precise and flexible enough that it could be done without natural language? The problem with using a schema language is that there will always be details it can't express that will have to be out-of-band or pushed into HTML docs anyway.