Re: dwbp-ISSUE-213 (BP_REST): Changes on BP about REST APIs [Best practices document(s)]

Yes, I think it’s helpful to be able to answer the people who are asking “how can I be the best webby data person I can possibly be?”, though I would put the question in less self-centered terms: “How can I share data via the web so that its future usefulness is maximized?”  I think we should also be attempting to answer the question “how can I do a better job, given the resources I have, of publishing my data so that more people can use it and trust it.”  My goal as a data publisher is always to make the data available and usable. I have to work within the real-world constraints of limited resources. I think our readers will similarly be looking for the biggest bang for their buck.

That said, I do think we should recommend using an API, but I think we should do so in such a way that people with both questions are well served. Even among those with high interest in doing the best possible job, there are two major schools of thought about how to build an API. I proposed a BP based on what those two schools have in common and outlined the two approaches as possible implementations[1]. The BP I suggested was "Make your data available through an API if you have the resources to do so."

I feel pretty strongly that we need to accommodate both points of view. If the only way to be “webby” is by publishing data with a truly RESTful API, I can’t honestly recommend that. A best practice should be something the majority of practitioners agree is best. Most of the practitioners that I know of aim for pragmatic REST (a term that I’m finding myself more comfortable with these days) when they build an API and often need to publish in an environment where setting up an API for everything is simply not affordable. If we suggest that there is only One Right Way, I think we will lose the interest and trust of a large number of people who might benefit from our BP doc.

I don’t mean that we need to tread so lightly that we make no impression, and I have at times felt that our BPs don’t push hard enough against the common foibles, but one can go too far in the other direction as well.
-Annette

[1] https://docs.google.com/document/d/13q2CvZjMkjXrg7Pv7aTRuU5UL2J_-py09Vs_zJoaLso/edit

> On Nov 13, 2015, at 11:51 PM, Erik Wilde <erik.wilde@dret.net> wrote:
> 
> hello annette.
> 
> On 2015-11-14 00:02, Annette Greiner wrote:
>> My reason for asking is that I think it's important to consider possible
>> use cases for doing something other than publishing an API. I realize it
>> doesn't meet your criteria for being "webby", but there are people who
>> use the web in other ways, and they may have good reason for doing so. I
>> don't want to be dismissive of them.
> 
> that's certainly a good goal to have. if people just want to get guidance how to create data models that they may or may not make available for download through some channel, then it's certainly good if there is some guidance available.
> 
> the only point i am trying to make is that if people specifically look for how to do that well *with a web focus*, then the spec should clearly state:
> 
> - *do not* separate *data* and *API* because that's not the best path to creating and publishing webby data.
> 
> - *do* keep in mind that webbyness is inherent in data models (such as linked data and web data), and that trying to completely separate data and API is problematic.
> 
> and again, you are certainly right that many (or probably most) people will not strive (or have the freedom) to create perfect linked or web data. and it would be good for the spec to take that into account.
> 
> all i am saying is that for those who specifically go to the spec with the question "how can i be the best webby data person i can possibly be", there should be clear and clean answers.
> 
> cheers,
> 
> dret.
> 
> -- 
> erik wilde | mailto:erik.wilde@dret.net |
>           | http://dret.net/netdret    |
>           | http://twitter.com/dret    |

Received on Saturday, 14 November 2015 23:25:09 UTC