Re: RE: [DWBP + SDW: API] Related Best Practice

The other aspect that is not well handled in most SOA platforms is the
relationship between the content model and the service model - its not
enough to describe the content without being able to describe the domain
and range of parameters of APIs. In the SIRF experiment we showed this can
be handled by, for example the RDF-QB binding of domain and range of
dimension specifications, and then binding these to parameterised URL via
void:technicalFeature annotation. This is not the only possible way - but
the separation of concerns is important to allow each aspect to be usefully
expressed and the re-use of semantics where applicable across content and
service descriptions is the key.

As a quick grounding example, in many countries a telephone book may not be
exposed via a search on address - (so bad folk cant turn up at a likely
looking place and find the phone number to call to check if it is
unoccupied).. This is a service interface restriction which is not easily
expressed from the content model and explanation of a result set. Other
examples include large datasets where only some dimensions are indexed or
queryable at all - maybe because of the way data is partitioned in the
storage layer.

Obviously the service description needs to share elements, but is not
identical to the content description. I dont really feel this is well
articulated in most existing architectures - but is achievable with "best
practice" even if mishandled or ignored in "common practice"

Rob Atkinson

On Thu, 31 Mar 2016 at 19:05 Linda van den Brink <l.vandenbrink@geonovum.nl>
wrote:

> Hi Ig,
>
>
>
> Yes, I agree you could shorten the Intended Outcome, for example like
> this:
>
>
>
> The whole set of information related to the API—set of values, how to use
> it, notices of recent changes, contact information, and so on—should be described,
> easily browsable on the Web, and accessible to humans and machines.
>
>
>
> And then move the rest of the contents to the Possible Approach. In that
> section you could also add the statement “API documentation should
> describe the data(set) it exposes” which is in your text already
> implicitly, but I thought it a good thing to have this explicit.
>
>
>
> Linda
>
>
>
> *Van:* Ig Ibert Bittencourt [mailto:ig.ibert@gmail.com]
> *Verzonden:* woensdag 30 maart 2016 19:36
> *Aan:* Linda van den Brink
> *CC:* public-sdw-comments@w3.org; Phil Archer
>
>
> *Onderwerp:* Re: RE: [DWBP + SDW: API] Related Best Practice
>
>
>
>
>
> Hi Linda,
>
>
>
> I copied the proposition of the merge between the BPs below. All the
> merges are presented in yellow. One point I would like to mention is about
> the intended outcome. I think it could be simplified (for example, saying
> that it should be possible for humans and machines to access the complete
> documentation) and the more detailed information could be presented in the
> Possible Approach to Implementation section.
>
>
>
> Please, let me know what do you think.
>
>
>
> Best
>
> Ig
>
>
>
>
>
>
>
> *Best Practice 27: Provide complete documentation for your API*
>
> *Provide complete information on the web about your API. Be sure to update
> documentation as you add features or make changes.*
>
>
>
> *Why*
>
> Developers are the primary consumers of an API and the API documentation
> is the first clue about the quality and usefulness of the API. When API
> documentation is complete and easy to understand, developers are probably
> more willing to continue their journey implementing it. In order to
> develop against it, they will need to understand how to use it. Providing
> comprehensive documentation in one place allows developers to code
> efficiently. Highlighting changes enables your users to take advantage of
> new features and adapt their code if needed.
>
> *Intended Outcome*
>
> The whole set of information related to the API—set of values, how to use
> it, notices of recent changes, contact information, and so on—should be described
> and easily browsable on the Web.
>
> Developers should be able to obtain detailed information about each call
> to the API, including the parameters it takes and what it is expected to
> return.
>
> The API should be self-documenting as well, so that calls return helpful
> information about errors and usage.
>
> Recent changes to the API itself should be readily discoverable by users.
>
> API users should be able to contact the maintainers with questions,
> suggestions, or bug reports.
>
> It should be possible for machines to access the API docummentaion in
> order to help developers build API client software.
>
> *Possible Approach to Implementation*
>
> A typical API reference provides a comprehensive list of the calls
> the API can handle, describing the purpose of each one, detailing the
> parameters it allows and what it returns, and giving one or more examples
> of its use. One nice trend in API documentation is to provide a form in
> which developers can enter specific calls for testing, to see what
> the API returns for their use case. There are now tools available for
> quickly creating this type of documentation, such as Swagger
> <http://swagger.io/>, io-docs <https://www.mashery.com/api/io-docs>,
> OpenApis <https://openapis.org/>, and others.
>
> EXAMPLE 30
>
> ·         OGC 'capabilities documents' provide an example of a
> standardized API description. EveryWFS
> <http://w3c.github.io/sdw/bp/#dfn-wfs> or WMS
> <http://w3c.github.io/sdw/bp/#dfn-wms> service, for example, understands
> the request 'getCapabilities', and then returns an XML document giving
> information about the service such as the Coordinate Reference system used,
> the data structure schema, available map layers, and so on.
>
> ·         Use of void:TechnicalFeature to describe the API for a (VoID)
> Dataset <http://www.w3.org/TR/void/#dataset> (or subset); providing a set
> of values, terms or entities for each API parameter (ref. CSIRO's Spatial
> Identifier Reference Framework <http://portal.sirf.net/about-sirf>). Use [
> RFC6570 <http://w3c.github.io/sdw/bp/#bib-RFC6570>] URI Templates to bind
> API parameters to RESTful URLs. A 'short-form' of the identifier may be
> required for usage in the API; this may be defined as a SKOS notation.
>
> ·         Use of Data Cube
> <http://www.w3.org/TR/vocab-data-cube/#data-cubes> with Dimensions (as
> specified in [vocab-data-cube
> <http://w3c.github.io/sdw/bp/#bib-vocab-data-cube>]) to define the data
> available from a predicably structured dataset - "what, where, when", and
> so on (ref. CSIRO'sSpatial Identifier Reference Framework
> <http://portal.sirf.net/about-sirf>); each Dimension of the Data Cube is
> bound to a parameter in the API method. The "where" Dimension of a Data
> Cube, if specified as aqb:CodedProperty, may bound to a set of
> SpatialThings (e.g. using the property qb:codeList). The URI Set (the set
> of all SpatialThings mentioned in the Data Cube) provides a 'controlled
> vocabulary' of locations for which 'observations' (data points) in the Data
> Cube are available (e.g. air quality data is available at these locations).
>
> ·         A versioned API: OpenStreetMap API
> <http://wiki.openstreetmap.org/wiki/API>
>
> ·         Use of HAL: 'JSON Hypertext Application Language', see IETF
> draft <https://tools.ietf.org/html/draft-kelly-json-hal-07>.
>
> ·         Use of Swagger <http://swagger.io/> and swaggerhub
> <https://swaggerhub.com/>; the Dutch Cadastre has published the WFS
> services in its national geo-portal, PDOK, as Swagger APIs on Swaggerhub,
> for example an API to get data about noise pollution near highways
> <https://swaggerhub.com/api/pdok/geluidskaarten/1.0>. Swagger also offers
> an example reference for a pet store API <http://petstore.swagger.io/#/>.
>
> ·         Packaging a coordinate transformation API for simple re-use.
>
> ·         Relating the API to its description using HTTP link headers.
>
> *How to Test*
>
> Check that every call enabled by your API is described in your
> documentation. Make sure you provide details of what parameters are
> required or optional and what each call returns. The quality of
> documentation is also related to usage and feedback from developers. Try to
> get constant feedback from your users about the documentation.
>
> Check the Time To First Successful Call
> <https://github.com/geo4web-testbed/topic3/wiki/Developer-Experience>
> (i.e. being capable of doing a successful request to the API within a few
> minutes will increase the chances that the developer will stick to your
> API).
>
> *Evidence*
>
> Relevant requirements: R-APIDocumented
> <http://www.w3.org/TR/dwbp-ucr/#R-APIDocumented>
>
> *Benefits*
>
> ·         [image: Reuse]
>
> ·         [image: Trust]
>
>
>
> 2016-03-30 11:07 GMT-03:00 Ig Ibert Bittencourt <ig.ibert@gmail.com>:
>
> Hi Linda,
>
>
>
> Thanks.
>
>
>
> It would be great if you could review.
>
>
>
> Best
>
> Ig
>
>
>
> 2016-03-30 10:49 GMT-03:00 Linda van den Brink <l.vandenbrink@geonovum.nl
> >:
>
> Dear Ig,
>
>
>
> Sounds very good. Let me know if you need me to review or whatever!
>
>
>
> Linda
>
>
>
> *Van:* Ig Ibert Bittencourt [mailto:ig.ibert@gmail.com]
> *Verzonden:* woensdag 30 maart 2016 15:43
> *Aan:* Phil Archer
> *CC:* public-sdw-comments@w3.org
> *Onderwerp:* Re: RE: [DWBP + SDW: API] Related Best Practice
>
>
>
> Dear Linda,
>
>
>
> Thank you for your feedback.
>
>
>
> In think we could improve the description of the DWBP:BP 27 (yes, now it
> is BP 27 [1]) by adding the details you proposed in your e-mail and also by
> adding about "the time to first successful call". In the beginning of the
> documentation, this is very well presented [2] :
>
>
>
>    - *API documentation is the first clue to your developer customer
>    about the quality and usefulness of the API. When API documentation is
>    complete and easy to understand, developers are probably more willing to
>    continue their journey implementing it. One important aspect here is the
>    Time To First Successful Call (TTFSC). Being capable of doing a successful
>    request to the API within a few minutes will increase the chances that the
>    developer will stick to your API.*
>
> I also lik the examples described in the SDWBP 29, which could be merged.
>
>
>
>
>
> @Phil - sorry about that. Now it is in the public-comments list. :-)
>
>
>
>
>
> [1] http://w3c.github.io/dwbp/bp.html#documentYourAPI
>
> [2] https://github.com/geo4web-testbed/topic3/wiki/Developer-Experience
>
>
>
> Best
>
> Ig
>
>
>
> 2016-03-29 5:55 GMT-03:00 Phil Archer <phila@w3.org>:
>
> For archive
>
>
> -------- Forwarded Message --------
> Subject: RE: [DWBP + SDW: API] Related Best Practice
> Date: Tue, 29 Mar 2016 08:34:05 +0000
> From: Linda van den Brink <l.vandenbrink@geonovum.nl>
> To: Ig Ibert Bittencourt <ig.ibert@gmail.com>, jeremy.tandy@gmail.com <
> jeremy.tandy@gmail.com>, p.barnaghi@surrey.ac.uk <p.barnaghi@surrey.ac.uk>,
> Bernadette Farias Loscio <bfl@cin.ufpe.br>, Caroline Burle <cburle@nic.br>,
> Newton Calegari <newton@nic.br>, Phil Archer <phila@w3.org>
>
> One link I forgot to supply with my answer, about API documentation and
> time to first successful call:
> https://github.com/geo4web-testbed/topic3/wiki/Developer-Experience
>
> Van: Linda van den Brink
> Verzonden: dinsdag 29 maart 2016 10:30
> Aan: 'Ig Ibert Bittencourt'; jeremy.tandy@gmail.com;
> p.barnaghi@surrey.ac.uk; Bernadette Farias Loscio; Caroline Burle; Newton
> Calegari; Phil Archer
> Onderwerp: RE: [DWBP + SDW: API] Related Best Practice
>
> Dear all,
>
> I think that indeed DWBP 26 and SDWBP 29 could be merged. I reviewed DWBP
> 26 and compared it to SDWBP 29. I think that SDWBP 29 might even be
> completely removed from the SDWBP, as there are no special spatial aspects
> in it (some examples aside), and DWBP 26 describes the issue sufficiently.
> However in SDWBP 29, there is currently a little more detail you could
> consider adding to DWBP 26. What I’m missing is:
>
> -          API documentation should describe the data(set) it exposes
>
> -          We recommend providing machine readable API documentation that
> can be used by software development tools to help developers build API
> client software. (or is that what you mean by self-documenting?)
>
> -          Where a parameter domain is bound to a set of values (e.g.
> value range, spatial or temporal extent, controlled vocabulary etc.), the
> API documentation or the API itself should indicate the set of values that
> may be used in order to help users request data that is actually available.
>
> An extra thing you could add, if you want, is a statement I learned from
> one of the participants of a testbed on data on the web we recently held.
> He said that a good measure for knowing if an API is well-documented is
> ‘the time to first successful call’.
>
> I hope this helps, my fellow SDW editors might also want to respond.
>
> Linda
>
> Van: Ig Ibert Bittencourt [mailto:ig.ibert@gmail.com]
> Verzonden: maandag 28 maart 2016 18:07
> Aan: jeremy.tandy@gmail.com<mailto:jeremy.tandy@gmail.com>;
> p.barnaghi@surrey.ac.uk<mailto:p.barnaghi@surrey.ac.uk>; Linda van den
> Brink; Bernadette Farias Loscio; Caroline Burle; Newton Calegari; Phil
> Archer
>
>
> Onderwerp: [DWBP + SDW: API] Related Best Practice
>
> Dear Editors of the Spatial Data on the Web Best Practices Document,
>
> My name is Ig Bittencourt and I am a member of the W3C Data on the Web
> Working Group. Two weeks ago we had our final F2F meeting and we discussed
> about our BP Doc [1]. In one of the discussions, we realized that SDW:BP 29
> [2] is very related to DWBP:BP 26.
>
> Both BPs are related to documenting APIs. However, in SDW:BP 29, there is
> a special atention on the self-description of APIs. However, if you look at
> the intended outcome of DWBP:BP 26, we discuss a little about it.
>
> For this reason, we started to wonder if these BPs could be merged.
> Please, let us know what do you think about this possibility.
>
> All the very best,
>
> [1] http://w3c.github.io/dwbp/bp.html
> [2] http://w3c.github.io/sdw/bp/#self-describing-apis
> [3] http://w3c.github.io/dwbp/bp.html#documentYourAPI
>
>
> Ig Ibert Bittencourt
> Professor Adjunto III - Instituto de Computação/Universidade Federal de
> Alagoas (UFAL)
> Vice-Coordenador da Comissão Especial de Informática na Educação
> Líder do Centro de Excelência em Tecnologias Sociais
> Co-fundador da Startup MeuTutor Soluções Educacionais LTDA.
>
>
>
>
>
> --
>
>
>
> Ig Ibert Bittencourt
>
> Professor Adjunto III - Instituto de Computação/Universidade Federal de
> Alagoas (UFAL)
>
> Vice-Coordenador da Comissão Especial de Informática na Educação
>
> Líder do Centro de Excelência em Tecnologias Sociais
>
> Co-fundador da Startup MeuTutor Soluções Educacionais LTDA.
>
>
>
>
>
> --
>
>
>
> Ig Ibert Bittencourt
>
> Professor Adjunto III - Instituto de Computação/Universidade Federal de
> Alagoas (UFAL)
>
> Vice-Coordenador da Comissão Especial de Informática na Educação
>
> Líder do Centro de Excelência em Tecnologias Sociais
>
> Co-fundador da Startup MeuTutor Soluções Educacionais LTDA.
>
>
>
>
>
> --
>
>
>
> Ig Ibert Bittencourt
>
> Professor Adjunto III - Instituto de Computação/Universidade Federal de
> Alagoas (UFAL)
>
> Vice-Coordenador da Comissão Especial de Informática na Educação
>
> Líder do Centro de Excelência em Tecnologias Sociais
>
> Co-fundador da Startup MeuTutor Soluções Educacionais LTDA.
>