W3C home > Mailing lists > Public > public-sdwig@w3.org > January 2021

Re: [sdw] Defining "convenience API" (#1243)

From: Clemens Portele via GitHub <sysbot+gh@w3.org>
Date: Tue, 26 Jan 2021 14:16:12 +0000
To: public-sdwig@w3.org
Message-ID: <issue_comment.created-767569429-1611670571-sysbot+gh@w3.org>
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.]

GitHub Notification of comment by cportele
Please view or discuss this issue at https://github.com/w3c/sdw/issues/1243#issuecomment-767569429 using your GitHub account

Sent via github-notify-ml as configured in https://github.com/w3c/github-notify-ml-config
Received on Tuesday, 26 January 2021 14:16:14 UTC

This archive was generated by hypermail 2.4.0 : Thursday, 24 March 2022 20:31:04 UTC