Re: APIs to work with data on the web

Hi,

I'm not a working group member, but wanted to chime in here.

I work as an Open Data consultant, with part of my time spent working at
the Open Data Institute in the UK (my comments here are my own). I'm very
interested to see the deliverables from this group as this is a really
important area.

As someone who works with a variety of data publishers and consumers,  I'm
looking for this working group to help document and promote a set of best
practices that apply to the existing ways in which people are putting data
onto the web, *not* to recommend a single best way to do that. There is
already a set of emerging best practices, recommendations and guidance
which can be brought together by this group and given a seal of approval by
the W3C.

Many of those best practices are orthogonal to the means by which the data
itself is published. Whether the data is accessed in bulk (downloads) or
on-demand (APIs, Linked Data) there are some common things that data
publishers should do in order to make that data useful, for example:

* ensure its documented
* ensure its supported and regularly released
* ensure the release schedule is described
* ensure that there are clear feedback loops for corrections, updates
* ensure it is clearly licensed
* ensure that there is a stable link to the data
* ...etc

Many of these issues are captured and described by applications like the
Open Data Certificates, but not all of them are yet covered by
machine-readable vocabularies.

There are some specific recommendations that can also be made that apply to
the means by which data is published:

* If you're publishing bulk downloads, then how do you support that with
machine-readable metadata? E.g. as part of a data package
* If you're publishing a SPARQL endpoint, then should you also publish a
SPARQL Service Description document, etc.
* If you're publishing Linked Data then how best to construct your URIs?
(Ref: UK government URI guidance)
* ...etc

Separating out the issues into general recommendations, that help build
trust and reliability into online data, from specific technology specific
recommendations seems like a useful way forward to me.

It also important to recognise that publishers may want or need to support
multiple ways to access the same dataset. For example when we built the
Ordnance Survey Linked Data platform this was to supplement their existing
bulk download options with both a Linked Data view and a set of APIs. This
was to support the widest possible set of consumer needs. E.g. everything
from local bulk indexing, through to simple online browsing of the data.

In terms of the use cases that are being compiled, I think its really
important to prioritise the needs of the data consumer rather than the
publisher. Its the consumers that need to be supported by data publishers
doing improving their publication processes (incl. providing
machine-readable data). Publishers will also benefit but through the
network effects of more consumers using their data. By focusing on specific
issues that consumers are facing I think it will be easier to turn those
into actions for the group.

So from a use case perspective I'd suggest focusing them on specific
questions such as:

* as a data consumer, how do I identify the source of this data?
* as a data consumer, how do I know how this data has been collected?
* ..., how do I provide corrections?

Cheers,

L.



On Tue, Mar 18, 2014 at 1:18 PM, Steven Adler <adler1@us.ibm.com> wrote:

> Thanks.  A few people have agreed with our position below, but some still
> like the idea of API's for accessing Data.  What is the process W3C uses to
> resolve these points of view and when it is resolved, does the conclusion
> get written into the Best Practices draft and/or do we also include the
> lineage of the conclusion - that is, we we present the pros and cons and
> reasons for the conclusion by also relating what we didn't recommend and
> why?
>
>
> Best Regards,
>
> Steve
>
> Motto: "Do First, Think, Do it Again"
>
>
>  From: <Manuel.CARRASCO-BENITEZ@ec.europa.eu> To: Steven
> Adler/Somers/IBM@IBMUS, <Deirdre.Lee@deri.org> Cc: <mail@makxdekkers.com>,
> <newton@nic.br>, <public-dwbp-wg@w3.org> Date: 03/18/2014 08:21 AM
> Subject: RE: APIs to work with data on the web
> ------------------------------
>
>
>
> +1
>
> -        Resources should be addressable with a URI
> -        One should aim a common interface for humans and machine
>
> *http://www.w3.org/2013/dwbp/wiki/Data_on_the_Web_URI_Best_Practices*<http://www.w3.org/2013/dwbp/wiki/Data_on_the_Web_URI_Best_Practices>
>
> Regards
> Tomas
>
> *From:* Steven Adler [mailto:adler1@us.ibm.com <adler1@us.ibm.com>]
> * Sent:* Monday, March 17, 2014 4:34 PM
> * To:* Lee, Deirdre
> * Cc:* Makx Dekkers; Newton Calegari; public-dwbp-wg@w3.org
> * Subject:* RE: APIs to work with data on the web
>
> Excellent use case which begins to explore and spell out the advantages
> and trade-offs of using API's to access Open Data.  I would like to explore
> this topic in greater detail.  My own personal preference is data access by
> HTTP and URI, because it provides a common interface for humans and
> machines.  But are there performance implications?
>
>
> Best Regards,
>
> Steve
>
> Motto: "Do First, Think, Do it Again"
>
>  From: "Lee, Deirdre" <*Deirdre.Lee@deri.org* <Deirdre.Lee@deri.org>>  To: Newton
> Calegari <*newton@nic.br* <newton@nic.br>>, Makx Dekkers <
> *mail@makxdekkers.com* <mail@makxdekkers.com>>  Cc: "
> *public-dwbp-wg@w3.org* <public-dwbp-wg@w3.org>" <*public-dwbp-wg@w3.org*<public-dwbp-wg@w3.org>
> >  Date: 03/17/2014 11:19 AM  Subject: RE: APIs to work with data on the
> web
>
> ------------------------------
>
>
>
>
> Hi all,
>
> Very interesting article indeed and related to discussions we're currently
> having with developers as part of Open Data Ireland on how best to
> publish/use machine-readable data.
>
> I've added a use-case on it *https://www.w3.org/2013/dwbp/wiki/Use_Cases*<https://www.w3.org/2013/dwbp/wiki/Use_Cases>Please feel free to add points or pick up on nuances of the conversation
> that I missed. Perhaps we could break this into multiple use-cases to look
> at each of the aspects in more detail?
>
> Cheers,
> Deirdre
>
>
> * From:* Newton Calegari [*mailto:newton@nic.br* <newton@nic.br>]
> * Sent:* 17 March 2014 13:19
> * To:* Makx Dekkers
> * Cc:* *public-dwbp-wg@w3.org* <public-dwbp-wg@w3.org>
> * Subject:* Re: APIs to work with data on the web
>
> Hi Laufer, I didn't know the Socrata.
> Thanks for share the link, Makx. Very interesting text and point of view
> about APIs.
>
> BR,
>
> Newton
>
> Em 14/03/2014, à(s) 15:58, Makx Dekkers <*mail@makxdekkers.com*<mail@makxdekkers.com>>
> escreveu:
>
>
> For a different perspective on APIs, see this:
> *http://ruben.verborgh.org/blog/2013/11/29/the-lie-of-the-api/*<http://ruben.verborgh.org/blog/2013/11/29/the-lie-of-the-api/>
>
> Makx.
>
> * From:* Newton Calegari [*mailto:newton@nic.br* <newton@nic.br>]
> * Sent:* Thursday, March 13, 2014 6:03 PM
> * To:* *public-dwbp-wg@w3.org* <public-dwbp-wg@w3.org>
> * Subject:* APIs to work with data on the web
>
> Hi all,
>
>          Last week, Yaso and I were talking about APIs and how they are
> important in all aspects of data on the web. APIs are one of the simplest
> ways to access and to distribute data across the web, and we think that is
> an important subject to be discussed on the WG.
>          To talk about APIs, we obviously need to discuss about URI and
> descriptors. Carrasco written the first document [*1*<http://www.w3.org/2013/dwbp/wiki/Data_on_the_Web_URI_Best_Practices>]
> about it, besides there are a few messages discussing it.
>          Moreover, I want to share some links I consider relevant and
> useful to discuss about this topic.
>          Joshua Bloch, a software engineer and former *Googler*,
> published an article on InfoQ [*2*<http://www.infoq.com/articles/API-Design-Joshua-Bloch?utm_source=buffer&utm_campaign=Buffer&utm_content=buffer36801&utm_medium=twitter#.UvbdCPy0BT0.delicious>]
> site and made a presentation called "How to Design a Good API & Why it
> Matters" [*3* <http://www.infoq.com/presentations/effective-api-design>]
> (other Jushua's presentation about the same subject, but the video is
> hosted on YouTube [*4* <https://www.youtube.com/watch?v=aAb7hSCtvGw>]).
> These links are very interesting and I recommend to all of you, even who is
> already expert in API design.
>
> [1] Data on the Web URI Best Practices:
> *http://www.w3.org/2013/dwbp/wiki/Data_on_the_Web_URI_Best_Practices*<http://www.w3.org/2013/dwbp/wiki/Data_on_the_Web_URI_Best_Practices>
> [2] Joshua Bloch: Bumper-Sticker API Design:
> *http://www.infoq.com/articles/API-Design-Joshua-Bloch?utm_source=buffer&utm_campaign=Buffer&utm_content=buffer36801&utm_medium=twitter#.UvbdCPy0BT0.delicious*<http://www.infoq.com/articles/API-Design-Joshua-Bloch?utm_source=buffer&utm_campaign=Buffer&utm_content=buffer36801&utm_medium=twitter#.UvbdCPy0BT0.delicious>
> [3] How to Design a Good API & Why it Matters:
> *http://www.infoq.com/presentations/effective-api-design*<http://www.infoq.com/presentations/effective-api-design>
> [4] How to Design a Good API & Why it Matters (YouTube version):
> *https://www.youtube..com/watch?v=aAb7hSCtvGw*<https://www.youtube.com/watch?v=aAb7hSCtvGw>
>
> Best Regards,
> Newton
>
>
>


-- 
Leigh Dodds
Freelance Technologist
Open Data, Linked Data Geek
t: @ldodds
w: ldodds.com
e: leigh@ldodds.com