Defining "convenience API"

[lvdbrink]

The OGC Architecture Board has been trying to define the term "convenience API". I pointed them to the description in https://www.w3.org/TR/sdw-bp/#convenience-apis. This could be the basis of their definition, but it seemed from the discussion I had with them that they were looking for a somewhat less narrow definition.

I re-read the BP myself and think that the descriptions under Why and Intended outcome provide good input for a definition.

Some key quotes from the BP:

tailored to meet a specific goal; enabling a user to engage with complex data structures using (a set of) simple queries

provides a coherent set of queries and operations, including spatial ones, that help users get working with the data quickly to achieve common tasks. The API provides both machine readable data and human readable HTML markup. The human-readable markup will also support search engine's Web crawlers to enable indexing of spatial data.

... And there's more under Possible approach for implementation, although these are perhaps too specific for a definition - they are more like suggestions on how to make a spatial data API convenient:

well documented and easy to understand, both in terms of the options to access / filter the data and of the data structures that are returned

Return data in chunks fit for use in Web applications and as useful sets of information.

simplifying the geometries

overly small pieces of data are inconvenient to use

Support queries for Spatial Things based on user needs

Do we still think all these are aspects of (spatial) convenience APIs? Is there more?

[cportele]

The text before the Best Practice also provides more background on the term and why it was introduced. In 2016 our analysis was in general we could distinguish three types of patterns for sharing spatial data:

When determining the mechanism to be used to provide Web access to data, publishers need to assess utility against cost. In order of increasing usefulness and cost:

1. Bulk-download or streaming of the entire or pre-defined subsets of a dataset
2. Generalized spatial data access API
3. Bespoke API designed to support a particular type of use

Item 2 were the APIs implementing the OGC WxS / GeoSPARQL / etc. standards - in general rich capabilities, complex to learn and use, full access to raw data.

Item 3 were the "convenience APIs" that were focussed on a specific use and easier to learn and use. These are what Best Practice 12 is about.

What we have seen since we published the Best Practices document is that OGC is now trying to specify data access API standards that are still generalized (i.e., the same API building blocks are applicable to many datasets), but at the same time have a more focused scope (i.e., not try to support all the edge cases) and APIs implementing them should be easier to learn and use. In this context it is also relevant that the OGC API standards do not specify standardized APIs, but API building blocks that can be used in APIs, including in bespoke APIs.

For some types of use an API using API building blocks from the OGC API standards can be in both categories 2 and 3 (actually, in all three categories).

We also had discussions about the term in the drafting process, but eventually kept it, because we weren't able to come up with a better term or identified one that was in use elsewhere, but we still wanted to make clear that there is range of options how to design/implement a spatial data access API - and highlight to readers that sharing the data (only) via a standardized API may not be the most useful way to share it with many users. See also the section "Why are traditional Spatial Data Infrastructures not enough?"

If the OGC Architecture Board wants to define the term based on its use in the Best Practices document, I would suggest reading the whole section "Spatial data access" as a starting point.

[As an aside, I think we should update the "Spatial data access" section in the planned revision of the BP document with some of that discussion.]