Enabling Web Services


Not surprisingly, the State of Utah has a large amount of data and much of it is public.  Some of the data that holds the most interest to people is already available on our web site for searching.  For example, you can verify the validity of a professional license.  My plan is to enable web services by ensuring that anytime we make data available we do it in a way that produces at least XML and that URIs work for all queries (yes, RESTian principles are at play here). 

Let's face it, if we're going to build an application that lets someone query a database its a shame not to return XML since we can do it for little additional cost and the potential benefits are huge.  With that thought, I've been trying to come up with a set of principles that we can follow in state government to ensure that this happens. 

Without further ado, here is a list of principles I have so far.  What am I missing? 

  1. RSS should be produced, and the presence of an RSS feed clearly indicated, where applicable. For example, RSS feeds should be produced for events, press releases, chronological data such as rulings, judgments, and other decisions, etc.
  2. All queries for data from a web server should produce at least XML. If human readability is required, post process the XML with XSLT.  As an example, if I go to the professional licensing division and query about doctors, the application should, at a minimum, produce XML.
  3. Data queries should be accessible as a URI and a URI should be associated with each resource (a resource includes even a single data element). For example, I should be able to query for a professional license using a URI like: http://www.dopl.utah.gov/llv?last_name=windley (this is not a valid URI.) If this query returns a list of results, each of those results should be available individually as XML using a URI reference. 
  4. The API for this URI query language should be clearly documented using WSDL (?) and its location clearly identified.
  5. Avoid using a POST for queries.
  6. Use standards for XML where available rather than making up your own.  A good example is RSS.  Organizations that you belong to may already be developing XML standards for the type of data you have.  Still, dive in and keep moving; if you miss a standard its not the end of the world because its likely your data can be translated using XSLT into whatever standards come along later.
  7. Document whatever XML format you output using a DTD and ensure that the up to date DTD is available online and referenced in the generated XML.
  8. Consider displaying your data in multiple flavors to serve multiple audiences.  At a minimum, most queries will produce at least one flavor of XML and HTML. Once you're producing the XML, its easy to display the data in multiple flavors by translating the base XML using XSLT.
  9. Include metadata with your XML. The Dublin Core elements in RDF are endorsed by the state GILS project and the CIO's office. The GILS project has produced templates and schema specific to the State of Utah for the Dublin Core.
  10. Use WSIL to advertise the availability of your service.   If it becomes viable in the future we will use UDDI, but having everything documented in WSIL will make that step relatively easy. 
  11. Use web authentication and authorization for queries that require it, rather than a homegrown solution, so that single sign on from the statewide directory works and queries can be made using a URI instead of a post.
  12. URIs should be carefully designed (yes, designed) so that they are meaningful and unlikely to change in the future.  The URI is the public interface for your resource and, consequently, deserves great thought.  See "Cool URLs Don't Change" for more information. 

Please leave comments using the Hypothes.is sidebar.

Last modified: Thu Oct 10 12:47:20 2019.