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

Hi Linda and Ron,

Thanks for your comment.

@Linda, I am going to change the BP based on your suggestions and make the
statement "API documentation should describe the data(set) it exposes"
explicit in the Implementation Section.

@Ron, very nice example. I know that there were some academic experiments
with Semantic SOA and Semantic Services, but not sure this evolved from 5
years ago. With regards SIRF experiment, please let me know if it is the
second one from the merged BP I sent to this list.

Best,
Ig

2016-03-31 8:37 GMT-03:00 Rob Atkinson <rob@metalinkage.com.au>:

> 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.
>>
>


-- 

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.