Re: APIs to work with data on the web

Leight,

This is very helpful.  In the article I shared, there was a debate about 
using URIs or APIs, and in the perfect work we might write Best Practices 
that recommend using URI's to access Data on the Web - creating a common 
interface for humans and machines.  But we don't live in the perfect world 
and no matter what we write a lot of developers will continue to use APIs 
to access Data on the Web. 

Better for us to embrace the world that we live in and write 
recommendations that are meaningful for anyone in any way they access 
Data.  And based on this discussion, that could mean:

1.  Accessing Data via URI
2.  Accessing Data via URI's as parameters within API's
3.  Accessing Data via API's when no URI's are present
4.  Accessing Data by means other than API or URI

That's my take so far.  What do others think?


Best Regards,

Steve

Motto: "Do First, Think, Do it Again"



From:
Leigh Dodds <leigh@ldodds.com>
To:
Steven Adler/Somers/IBM@IBMUS
Cc:
Manuel CARRASCO-BENITEZ <Manuel.CARRASCO-BENITEZ@ec.europa.eu>, laufer 
<laufer@globo.com>, Deirdre Lee <Deirdre.Lee@deri.org>, mail 
<mail@makxdekkers.com>, newton <newton@nic.br>, public-dwbp-wg 
<public-dwbp-wg@w3.org>
Date:
03/18/2014 02:50 PM
Subject:
Re: APIs to work with data on the web



Hi,

On Tue, Mar 18, 2014 at 6:33 PM, Steven Adler <adler1@us.ibm.com> wrote:
> Is not a URI an application programming INTERFACE?  And would we not 
wish
> the use of URIs to be recommended in APIs?

We access APIs via a URI. Good, hypermedia based APIs will return
standardised documents that describe how to interact with that
interface. Those APIs are part of the web.

But many APIs don't do that and you have to read docs, etc in order to
understand how to interact with them. Those APIs aren't as well
integrated into the web architecture.

There are best practices for publishing APIs. I'd suggest that those
best practices overlap only partly with data publishing best
practices. Details on how to publish a good hypermedia API are a wider
issue than data publishing.

Where they overlap is in:

* ensuring that metadata about the dataset accessed via the URI, e.g.
its source, licensing, is available to consumers. Ideally this should
be available from the API endpoint and its responses
* that API responses use standard web formats where possible, so data
is more easily reused
* ideally, API responses should include URIs to faciliate linking and
discovery of data.

Does that help?

Cheers,

L.

>
> Forgive me if this is a dumb question.
>
> Regards,
>
> Steve
>
> ________________________________
>
>   From: Leigh Dodds [leigh@ldodds.com]
>   Sent: 03/18/2014 04:38 PM GMT
>   To: Manuel.CARRASCO-BENITEZ@ec.europa.eu
>   Cc: laufer@globo.com; Steven Adler; Deirdre.Lee@deri.org;
> mail@makxdekkers.com; newton@nic.br; public-dwbp-wg@w3.org
>
>
>   Subject: Re: APIs to work with data on the web
>
>
> Hi,
>
> On Tue, Mar 18, 2014 at 4:23 PM, <Manuel.CARRASCO-BENITEZ@ec.europa.eu>
> wrote:
>>
>> Forgot ... nothing wrong with having APIs in addition to URIs; but it 
is
>> essential to have URIs.
>
>
> It's more useful to characterise this as a SHOULD rather than a MUST
> (essential), and also fine tune what those URIs are representing
>
> For example:
>
> If you want to publish "3 star data" then you MUST have a stable URI for 
the
> dataset and SHOULD have a URI for each version of the dataset (for
> archiving), as well as a "latest version" URI. Those are best practices 
to
> support linking and archiving of datasets.
>
> If you want to publish "5 star data" then you MUST have a stable URI for
> everything in your dataset AND the dataset, or re-use existing URIs.
> Publishing Linked Data is a best practice, and the use of URIs follows 
from
> that (you can't do Linked Data otherwise).
>
> There are specific best practices for creating cool, useful URIs for 
both of
> these scenarios. I've captured some of those patterns here:
>
> http://patterns.dataincubator.org/book/identifier-patterns.html
>
> Cheers,
>
> L.
>



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