dwbp-ISSUE-242 (Laufer): APIs on the Web (for publishing Data on the Web) Best Practices [Best practices document(s)]

dwbp-ISSUE-242 (Laufer): APIs on the Web (for publishing Data on the Web) Best Practices [Best practices document(s)]

http://www.w3.org/2013/dwbp/track/issues/242

Raised by: Carlos Laufer
On product: Best practices document(s)

I was in the joint meeting with SDW and in the last minutes they raised a question about APIs. They commented that they are thinking about some set of operations that would be interesting to have in such APIs as, for example, "Search".

Our document is about Best Practices for Publishing Data on the Web and we have some BPs that talk to users that deal with the data itself, and other BPs that talk to users that develop the way these data are published, for example, via an API.

We have 3 explicit BPs to APIs (besides other BPS that use the term API in their descriptions):
"BP10: Avoid Breaking Changes to Your API, Communicate Changes to Developers"
"BP25: Document your API"
"BP26: Use an API"

They are Best Practices for Web APIs. A good Web API will have other issues. I do not know how much deeper we will go in defining Best Practices to Web APIs (for publishing data), as for example, suggesting a set of operations. 

We can talk about BPs for describing data, for example the metadata about structure. Another thing is the application that distributes these data. Having an URI that access data is a kind of download (maybe a too strong assertion). An API (in our context) is an application that returns data. In that sense, we can see this API even as the web interface of a Datastore, and it could be, for example, Elastic Search, a SPARQL endpoint, etc.

Maybe it would be worthwhile to separate this two types of BPs in the document, and explain the differences about the audience of them.

We will also have to decide how much we will orient the users about developing a good API for publishing data on the web.

Received on Thursday, 18 February 2016 11:53:09 UTC