Definition of web services

A Web service is a server running on a computer device, listening for requests at a particular port over a network, serving web documents (HTML, JSON, XML, Images), and creating web applications services, which serve in solving specific domain problems over the web (www, internet, HTTP)

https://en.wikipedia.org/wiki/Web_service

API (Application Programming Interface)

This is a gateway to communicate with an application. This is most of the time used to access data stored in the server, but it can also be required to send data to the web service, or request some functions (apply a prediction model, …). This is the entry point to an application.

A web service is a sub-part of APIs.

The request are made using the HTTP application protocol.

A web service is usually a layer of abstraction that disconnect the user from the technical architecture of the data (what kind of database, what language, which location). The only requirement if to provide the correct input/output format. This format is often the JSON format. That involve parsing from and to JSON to communicate with a web service.

In REST Web services. The actions are generally identified by a verb among GET, POST, UPDATE, DELETE, that follows the CRUD (Create, Read, Update, Delete) principles. Update and Delete are generally reserved for admin rights.

Little summary :

• API
  • Web Services
    • REST API webservices

Authentication

An important difference between APIs concerns the authentication rights. Depending on the privacy of the data handled, the API is more or less open. It can vary from a fully open API with no authentication to a private API with a strong privacy handled by cryptographic keys (tokens).
Usually an identification by username and password coupled by the presence of groups deals with the privacy issues.

Documentation of the web service

An API is a multitude of several services, which all have a dedicated action. In order to explore and request the appropriate service. You need a proper documentation.
Unfortunately all documentations are not following the same rules making the first steps more or less feasable. The public transport of Brest proposed a human readable documentation here for example. There is also a machine-readable documentation propoosed by Open-API and the software swagger.

Example of Brest transport

#The address of the webservice
brestStopsNames = "https://applications002.brest-metropole.fr/WIPOD01/Transport/REST/getStopsNames?format=JSON"
StopsNamesjson = httr::GET(url = brestStopsNames, encode="json")
# transform http response object into a JSON object and finally into a R object
StopsNames = jsonlite::fromJSON(httr::content(StopsNamesjson,  as = "text",  encoding = "UTF-8"))
head(StopsNames)

brestRoutes = "https://applications002.brest-metropole.fr/WIPOD01/Transport/REST/getRoutes?format=%7bformat%7d"
Routesjson = httr::GET(url = brestRoutes , encode="json")
Routes = jsonlite::fromJSON(httr::content(Routesjson,  as = "text",  encoding = "UTF-8"))
head(Routes)

The arguments are put in the URL as a request (following the ?). The difficulty is to write correctly this URL to perform the appropriate request. A R friendly approach is to create a list with the various arguments and concatenate the list with the base URL. This is the first step to create a function! To know the arguments you should read the documentation.

#https://applications002.brest-metropole.fr/WIPOD01/Transport/REST/getStop?format=json&stop_name=malakoff
# The parameters of the 'function'
baseBrest = "https://applications002.brest-metropole.fr/WIPOD01/Transport/REST"
serviceBrest = "/getStop?"
attriBrest = list(
  format = "json",
  stop_name = "malakoff"
)

# the process of the 'function'
URLBrest = paste(baseBrest, serviceBrest, sep = "")
urlParamsBrest = ""
for (attribut in names(attriBrest)) {
  if (urlParamsBrest != ""){
    urlParamsBrest = paste0(urlParamsBrest, "&")
  }
   #   character arguments
  if (is.character(attriBrest[[attribut]])){
    urlParamsBrest = paste0(urlParamsBrest, attribut, "=", utils::URLencode(attriBrest[[attribut]], reserved = TRUE))
    #   numeric arguments
  } else if (is.numeric(attriBrest[[attribut]])){
    urlParamsBrest = paste0(urlParamsBrest, attribut, "=", format(attriBrest[[attribut]], scientific = FALSE))
    #   other arguments
  } else {
    urlParamsBrest = paste0(urlParamsBrest, attribut, "=", attriBrest[[attribut]])
  }
}
BrestRequest = paste(URLBrest, urlParamsBrest, sep = "", collapse = "")

# The output of the 'function'
Stopjson = httr::GET(url = BrestRequest, encode="json")
Stops = jsonlite::fromJSON(httr::content(Stopjson,  as = "text",  encoding = "UTF-8"))
head(Stops)

Example of OpenSILEX PHIS

The documentation of the PHIS web services is generated through the swagger software, it allows you to perform some requests online.

wsurlTOKEN = "http://www.opensilex.org:8080/openSilexSandBoxAPI/rest/brapi/v1/token"
body = list(
  grant_type = "password",
  username = "admin@opensilex.org",
  password = toString(md5("admin"))
)
tokenjson = httr::POST(url = wsurlTOKEN, body = body, encode="json")
authorization = jsonlite::fromJSON(httr::content(tokenjson,  as = "text",  encoding = "UTF-8"))
print(tokenjson)
print(authorization)

# alternative
# raw = toJSON(finalbody, auto_unbox = TRUE)
# authorization = httr::POST(url = wsurlTOKEN, body = raw, encode="raw", content_type_json()) #le content_type_json est indispensable

Remarque : GET response will send the token in the URL (not secured) and POST response will send the token in the body (more secured) but still in plain text. authentication services should use httpS for encryption.

WSurlGET = "http://www.opensilex.org:8080/openSilexSandBoxAPI/rest/experiments?pageSize=20&page=0"
authorizationToken = authorization$access_token
ExperimentJSON = httr::GET(WSurlGET, config = httr::add_headers(Authorization = paste("Bearer ", authorizationToken, sep = "")))
Experiment = jsonlite::fromJSON(httr::content(ExperimentJSON,  as = "text",  encoding = "UTF-8"))
Experiment

WSurlPOST = "http://www.opensilex.org:8080/openSilexSandBoxAPI/rest/methods"
# you can send structured data to the web services, the big issue is translating it into a conveniant JSON format.
# services will also check the data you are sending (type, value, etc).
data = data.frame(
    label = "My_new_method",
    comment = "this is a test for G12_PyR!",
    ontologiesReferences =list(
        property = "http://www.w3.org/2004/02/skos/core#closeMatch",
        object = "http://www.cropontology.org/rdf/CO_715:0000139",
        seeAlso = "http://www.cropontology.org/ontology/CO_715/"
 )
)
 
dataJSON = httr::POST(WSurlPOST, config = httr::add_headers(Authorization=paste("Bearer ", authorizationToken, sep = "")), body = data, encode = "json")
data = jsonlite::fromJSON(httr::content(dataJSON,  as = "text",  encoding = "UTF-8"))
data

getMethod = "http://www.opensilex.org:8080/openSilexSandBoxAPI/rest/methods?pageSize=20&page=0&uri=http://www.opensilex.org/demo/id/methods/m012"
authorizationToken = authorization$access_token
methodJSON = httr::GET(getMethod, config = httr::add_headers(Authorization=paste("Bearer ", authorizationToken, sep = "")))
method = jsonlite::fromJSON(httr::content(methodJSON,  as = "text",  encoding = "UTF-8"))
method