I’ve been working with several folks recently who are dealing with the (common) challenge of accurately referencing unique identifiers from one system in another. In one case, the system in question is a public registry that provides unique identifiers as a web service (a bit like GeoNames). In the other case, there are a number of internal systems within a large organization that all need to reference common entities like Organization and Contact.
One of the issues here is how to produce the user interface for the client system. For example, you might have a form with a field that needs to uniquely reference an Organization and enter some additional information about it, but the canonical list of Organizations lives in another system (let’s call it “the server”). The standard approach is for the server to provide an XML or JSON API to return search results, and then the client system can use this raw data to make its form work (e.g. with an autocomplete widget).
Lately, though, I’ve been wondering whether it wouldn’t make sense for the server to take a more active role here, especially for entity lookups where the UI isn’t so clear-cut – for example, what if in addition to matching the Organization name it would be really helpful to filter by location and type? The client system can create this UI, and that might be fine when you only have one client. But if you have five clients, now you have to re-invent the same wheel five times, in different ways, with different developers.
I think it would be really interesting for the people developing the server system to think about offering an “injectable” user interface for their API – e.g. offering UI widgets that could be plug-and-play with standard HTML forms, that could transform a simple text field into a more sophisticated search-and-select interface to correctly retrieve the unique ID for the appropriate record. Some possible models here might include:
- A pop-down autocomplete widget that would match on the human-readable title of a record, but also offer filtering or other search interface elements.
- A minimal “Select on <service-name>” button next to a text field that could pop up a more complex search-and-select interface in a modal window.
I can see why this has traditionally been left to client systems to deal with – give them the data, and let them use it however they want. But while a raw-data API is indispensable, I see a lot of benefit to a server-supplied interface for complex entity lookups – you reduce development time, you give users a standard interface across systems, and you give the job of integrating the data API to the developers most familiar with it.
While many API providers also provide widgets – e.g. for embedding tweets or adding a Like or +1 button - I haven’t seen many that are intended to integrate with forms or other interfaces for user input. Any examples you can think of?