API Endpoints
This vignette provides brief summaries of the endpoints of the
roreviewapi
package. These are encoded within the identical
R/plumber.R
and
inst/plumber.R
files. All endpoints respond only to GET
calls.
1. editorcheck
This is the main endpoint called by the ropensci-review-bot
in
response to package submission. The call itself is configured as part of
an external service call in
`ropensci-org/buffy,
which passes the parameters specified there of:
repo
The GitHub repository from where the call originates, generallyropensci/software-review
;issue_id
as the number of the issue inrepo
describing the software submission; andrepourl
as specified in the submission template, and specifying the GitHub repository of the software being submitted, also in the format<org>/<repo>
.
This endpoint implements the following steps:
Call
roreviewapi::check_issue_template()
to check the existence and format of HTML variables included within the submission template. This function returns an empty string if the template is okay; otherwise a descriptive error message. The return value also includes a binary attribute,"proceed_with_checks"
, which is set toFALSE
only ifrepourl
is improperly specified. In this case the function returns immediately with a text string describing the error. Otherwise the string is carried through to the next step:The
pkgcheck::pkgcheck()
function is started as a background process, dumping bothstdout
andstderr
messages to specified logfiles (seestdlogs
endpoint, below).Any messages generated above are prepended to a return message that the package checks have started, that message delivered back to the bot, and ultimately dumped in the issue thread.
All messages, and the results of the pkgcheck::pkgcheck()
process, are dumped
to the specified issue_id
in the specified repo
.
2. editorcheck_contents
The editorcheck_contents
endpoint implements the main check
functionality of the editorcheck
endpoint without dumping any results
to the specified issue. It is primarily intended to aid debugging any
issues arising within checks, through the use of the stdlogs
endpoint
described below. This endpoint accepts the single argument of repourl
only.
3. mean
A simple mean
endpoint can be used to confirm that the server is
running. It accepts a single integer value of n
, and returns the value
of mean(rnorm(n))
.
4. stats_badge
This endpoint is used by the bot to extract the stats badge from those
issues which have one, in the form "6\approved-bronze-v0.0.1"
. This is
used in turn by the bot to respond to mint
commands used to change
badge grades.
5. log
The log
endpoint accepts a single parameter, n
, specifying the
number of latest log entries to retrieve. An example of the log entry
for this
submission
follows:
#> [1] "INFO [2021-10-07 16:48:14] 3.236.83.25 \"Faraday v1.7.1\" <ip>:8000 GET /editorcheck ?bot_name=ropensci-review-bot&issue_author=ewallace&issue_id=470&repo=ropensci%2Fsoftware-review&repourl=https%3A%2F%2Fgithub.com%2Fewallace%2Ftidyqpcr&sender=ewallace 200 1.964"
Each entry contains the following information:
Date and time at which call was made;
IP address and machine from which call was sent;
Method used to send call;
IP address to which call was delivered (always the address hosting the
roreviewapi
instance);http
method for the call (alwaysGET
for all endpoints encoded here);The endpoint called (one of the methods listed above);
The parameters submitted along with the call;
The HTTP status of the call (hopefully 200); and
The total duration of the call response.
The 7th item of parameters submitted along with the call is particularly
useful for debugging purposes; and is specified in this line of the
R/api.R
file.
6. clear_cache
This endpoint can be used to clear the server’s cache whenever desired
or required. This cache is mainly used to store the results of calls to
pkgcheck::pkgcheck()
.
The only effect of clearing the cache will be extra time taken to
regenerate any calls which were previously cached.
7. stdlogs
This is the most important endpoint for debugging problems within the
pkgcheck
process
itself. The endpoint accepts the single parameter of repourl
, and will
return the results of both stdout
and stderr
connections produced
during pkgcheck
.
These checks are hashed with the latest git head, ensuring that the
endpoint returns checks for the latest commit.