End the Endpoint Madness

Sean’s been writing about why the Open Geospatial Consortium (OGC) standards aren’t RESTful. Since the OGC seems to be my favorite punching bag these days, I thought I’d jump right into the fun.

Everything that’s wrong the the WxS Suite (that’s a fancy acronym for Web Map Server, Web Feature Server, Web Context Server, etc.) boils down to one thing – they are based on the fundamentaly flawed concept of service endpoints. A service endpoint is a program sitting on the network that defines its own API.
To make this more concrete, let’s follow Sean’s lead and pick on the Web Feature Service (WFS) standard. As Sean showed, a WFS service understands URIs like this:

/wfs?REQUEST=GetCapabilities
/wfs?REQUEST=DescribeFeatureType&typename=places
/wfs?REQUEST=GetFeature&typename=places

Do you see it API? Its hidden in the REQUEST parameter. A WFS service endpoint understands requests such as GetCapabilities, DescribeFeatureType, GetFeature, etc.

Is this important? You bet. It violates every tenent of REST as implemented on the Web.

The Tenets of REST

So what are these REST tenets? Glad you asked:

  • Everything of interest, called resources, are identified with URIs (in English – you can get to everything important on the web with a link)
  • Resources are manipulated, via their URIs, using a limited, uniform interface (in English – use HTTP’s verbs dummy!)
  • Clients interact with resources via representations, which summarize the state of a resource at any given time and often provide links to other states (in English – when you go to a website you get back a web page that contains links to other web pages).

So how do OGC service endpoints get this wrong?

First, they lock away their resource behind big, thick stone walls, pretending they don’t even exist. Any access to the resource must go through the service endpoints API. Heaven forbid the resources escape out onto the web, letting anyone link to them, bookmark them, query their state, etc.

Second, they haughtily impose their custom APIs over HTTP’s standardized verbs. Clearly what works every day for almost a billion web users couldn’t possibly work for viewing a few features.

Third, their representations are barren of links. Instead of a thriving neighborhood of interconnected plazas and quaint streets, they are abandoned, dark, scary culdesacs.

Time for a Rethink

Fixing OGC web services is easy – once you have the right mind set. Just a few changes will lead to vast improvements:

  1. Service points are anti-patterns. Abolish them.
  2. Everything gets its own URI – feature types, feature collections, features, queries, filters, every attribute on every feature, etc.
  3. Abolish the REQUEST parameter. Anything with a URI (feature types, features, queries, filters, etc). can only be created, updated and deleted using HTTP POST, PUT and DELETE.
  4. Representations, besides images, should overflow with links. GML includes XLink for a reason – use it.
  5. Never, ever, use POST to do a query. I know the argument – a complicated query is well nigh impossible to squeeze into a URI. Fine, I agree. Instead of grossly violating REST, turn the query into its own resource complete with a URI. Then your query becomes something like http://www.mywf.com?search=http://www.saved.queries/nearby_ice_cream_stores.
  6. Errors must be reported using the appropriate HTTP status codes. And absolutely do not invent new, random mime types to report errors like in WMS.

To do this right, go get a copy of the Atom Publishing Protocol and read it. And then read it again. When it talks about feeds think feature collections. When it talks about entries, think features. And when it talks about anything else, think twice, and then a third time, before doing anything different.

Leave a Reply

Your email address will not be published.

Top