[Bioc-devel] Writing examples for accessing web API

[Martin Morgan]

On 03/07/2017 02:35 PM, Welliton Souza wrote:
> Thank you Nan Xiao, I think it is a good solution for my case. I will put
> the definition of host outside the \dontrun{}.

Actually, generally, one doesn't want to work around tests with hacks, 
but either (a) address the underlying problem or (b) justify what the 
current behavior is and live with the warning. Writing  \dontrun{} 
doesn't help  at all -- it might work now, but will suffer from 'bit 
rot' in the future; example and vignette code is littered with examples 
like this.

The usual problem with web resources is that the functions that access 
them assume that the resource is reliably available, and that band width 
is infinite. In reality, the web resource is likely to experience 
periodic down time, and the band width can be cripplingly slow.

There are a few notes here

   http://bioconductor.org/developers/how-to/web-query/

discussing better practice for querying web resources. Avoiding 
infinitely querying a web resource and including a time out are two 
important steps.

Ideally one would like unit tests that verify that the web resource is 
in fact alive, and that the expected API is available. One would not 
necessarily test the entire API, but rely instead on serialized 
instances to ensure that one parses the correct information.

With examples, there is a combination of judicious use of web calls 
coupled with re-use of data from previous calls. The forthcoming 
BiocFileCache (https://github.com/Bioconductor/BiocFileCache) might be 
used to create a temporary cache used during the duration of the build / 
check, limiting the number of unique calls required while still exposing 
substantial functionality in the example pages.

Martin

>
> Welliton
>
> Em ter, 7 de mar de 2017 16:27, Nan Xiao <road2stat at gmail.com> escreveu:
>
>> - this check can be bypassed by
>> writing "partially working" examples,
>> for instance:
>>
>> #' token = "foo"
>> #' \dontrun{
>> #' api(..., token)}
>>
>> Best,
>> -Nan
>>
>> On Tue, Mar 7, 2017 at 2:13 PM, Welliton Souza <well309 at gmail.com> wrote:
>>
>> Hi Sean,
>>
>> It doesn't require authentication. I've been using this server (
>> http://1kgenomes.ga4gh.org) to provide working examples and do unit tests
>> but I am not responsible for this server. However the package was developed
>> to access any server endpoint that use the same API. There are many web
>> resources to cover, the package takes some time to run all examples.
>>
>> Welliton
>>
>>
>> Em ter, 7 de mar de 2017 16:03, Sean Davis <seandavi at gmail.com> escreveu:
>>
>> Hi, Welliton.
>>
>> Great question.  Just out of curiosity, what are the internet connection
>> requirements that preclude running examples?  Is authentication required?
>> Or are you connecting to a server that runs only intermittently?
>>
>> Sean
>>
>>
>> On Tue, Mar 7, 2017 at 1:57 PM, Welliton Souza <well309 at gmail.com> wrote:
>>
>> Hi,
>>
>> I am developing a package that access web API endpoints. I wrote the
>> examples within \dontrun{} due to internet connection requirements.
>> However, the BiocCheck reports that I should provide at least 80 % of
>> running examples. What I should do? The package is mainly focused on
>> accessing web API and processing response data.
>>
>> Best regards,
>> Welliton Souza
>>
>>         [[alternative HTML version deleted]]
>>
>> _______________________________________________
>> Bioc-devel at r-project.org mailing list
>> https://stat.ethz.ch/mailman/listinfo/bioc-devel
>>
>>         [[alternative HTML version deleted]]
>>
>> _______________________________________________
>> Bioc-devel at r-project.org mailing list
>> https://stat.ethz.ch/mailman/listinfo/bioc-devel
>>
>>
>>
>>
>> --
>> https://nanx.me
>>
>
> 	[[alternative HTML version deleted]]
>
> _______________________________________________
> Bioc-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/bioc-devel
>


This email message may contain legally privileged and/or...{{dropped:2}}