Resource Path Issue

One of the most contentious issues we face in API development is consensus on standard resource paths. API-Features uses /collections/{collectionId}/items. Other SWGs plan to use /collections/{collectionId}/coverage, /collections/{collectionId}/maps, etc. Which is correct?

There appears to be consensus on /collections/{collectionId}. At least for those resources which are typically distributed as collections. The final part of the path tells you something about the collection. A taxonomy of these path fragments could look something like this:

/coverage -> Measurements organized in a regular or irregular grid

/map -> 2D Rendered information displayable for human visual consumption

/tile -> A subset of a dataset based on area of interest and level of detail

/items -> Any

Wait a minute -- "Any"!!

What use is a path fragment which can be anything?

Actually, it’s the most useful of all.

OGC Web Services are built around a taxonomy of data types; maps, features, coverages, etc. It’s a data provider centric view of the world. But what if we took a user-centric view of APIs. What if collections are built around the information that a user needs to do their job?

Consider a first responder. They are going to need a building model, routes of ingress and egress, photographs, overhead imagery, utilities, an elevation model, and all sorts of other supporting data. Everything they need to respond to an incident at a specific location. And they are going to want it in one neat little package, a collection. So how is our first responder going to use “/collections/110_Maple_Avenue/”? /maps, /coverage, /routes all have value. But how do you access the collection contents as a whole? /items.

/items allows us to locate and access any content in the collection regardless of type. So the fundamental access path for any collection is /collections/{collectionId}/items. This does not mean that the other paths don’t have value, just at a different level.

We can view /coverage, /maps, etc. as profiles of /items. They both restrict and extend /items. They restrict in that they only provide access to a specific type of item in the collection. They extend in that they bring to the user a whole collection of tools which are only useful for that type of resource. So “/collections/110_Maple_Avenue/coverage” brings to the first responder all of the sub-setting and processing tools which come with coverage data. But only for that subset of the collection which is coverage data.

So what does /items actually return? A Feature collection.

Now that the outrage has had a chance to settle,

We tend to think of Features as vector data. But at its most fundamental level, a Feature is an empty container. It has neither type, identity, nor properties. So a Feature can grow up to be just about anything. Which is exactly the sort of construct we are looking for.

Under this approach, API-Common would define the bbox, limit, and datetime parameters and how they would be applied to a generic data item. Other API standards would specialize those capabilities for the unique properties of the resources they address.