Re: BPs around REST and APIs

hello annette.

On 2015-09-25 07:46, Annette Greiner wrote:
> I’ve cobbled together a proposed set of BPs for APIs and REST that attempts to take into account some of the things you were concerned about in the Data on the Web Best Practices doc. It’s in a Google doc at present. Can you take a look at it and provide feedback? This needs to be looked at by someone other than me who knows something about REST.
> https://docs.google.com/a/lbl.gov/document/d/13q2CvZjMkjXrg7Pv7aTRuU5UL2J_-py09Vs_zJoaLso/edit?usp=sharing

thanks a lot for that, i have made copious comments. generally speaking, 
to me the whole text still is taking the perspective of "design your 
data", and then, as a second and separate step, "design your API". i 
take issue with that perspective, which is why i made my initial comment 
about hypermedia.

if you start from a web perspective, you design your data/service to be 
webby. that's the starting assumption. you design it so that consuming 
applications can navigate it and access it in ways that hopefully work 
for them. these designs can be relatively simple (allow pages access so 
that clients can access the data piecemeal), or more sophisticated 
(allow filters so that clients can request specific "views" according to 
their needs).

regardless of the features you provide, once you are done designing the 
data and the navigation paths that can be used to access it, *that is 
your API*. your data *is* your API. that's the idea of the web, that 
your data is hypermedia that can be explored by hypermedia navigation. 
the actual API (on the technical level) is always the same, it's HTTP 
with whatever additions to the uniform interface that you think you need.

if you approach the issue from the two-step perspective (1: design data; 
2: design API), you're not really talking about webby data, you're 
simply talking about data that you also could make available via FTP or 
some other remote access protocol, and that you just happen to make 
available through some "web download link."

i do understand that in practice, a lot of data actually is designed and 
made available in this non-webby way, where the web simply becomes a way 
to "download the dataset" (i call this pattern "FTP via HTTP", and it's 
one of the REST anti-patterns we use in REST tutorials). but i do think 
that a document entitled "data on the web" should at least mention and 
describe the webby way to do it, and then maybe could also mention the 
non-webby way that often happens in practice. in the end, shouldn't such 
a document encourage data/service providers to be more webby, so that 
more data/services on the web actually are provided in webby ways?

thanks and cheers,

dret.

-- 
erik wilde | mailto:dret@berkeley.edu  -  tel:+1-510-2061079 |
            | UC Berkeley  -  School of Information (ISchool) |
            | http://dret.net/netdret http://twitter.com/dret |

Received on Friday, 25 September 2015 16:41:01 UTC