Commit e28cdb1c authored by Dorchies David's avatar Dorchies David
Browse files

refactor: rename "operation" to "endpoint" in code and documentation

parent 36073ae0
Pipeline #30405 passed with stages
in 1 minute and 21 seconds
#' Main internal functions for querying the Hub'eau APIs
#' Main internal functions for querying the Hub'eau API endpoints
#'
#' The function `doQueryApi` is called by all the function querying the APIs and return the raw data sent by the API.
#' The function `doQueryApi` is called by all the function querying the API endpoints and return the raw data sent by the endpoint.
#' Pagination of the queries is handled automatically and the returned [list] is the concatenation of all the results sent by the API.
#'
#' The function `get_available_params` returns the list of available query parameters for a given operation in an API.
#'
#' @details The functions `get_[api]_[operation]` call the function `doQueryApi` and convert the response in a convenient format for the user ([data.frame] or [tibble::tibble])
#' @details The functions `get_[api]_[endpoint]` call the function `doQueryApi` and convert the response in a convenient format for the user ([data.frame] or [tibble::tibble])
#'
#' @param api a [character] name of the API (e.g.: "indicateurs_services", "prelevements"...), see example for available APIs
#' @param operation a [character] name of the endpoint, see example for available endpoints in an API
#' @param params a [list] the list of parameters of the queries and their values in the format `list(ParamName = "Param value", ...)`, use the function [get_available_params] for a list of the available filter parameters for a given operation in an API and see the API documentation for their description
#' @param endpoint a [character] name of the endpoint, see example for available endpoints in an API
#' @param params a [list] the list of parameters of the queries and their values in the format `list(ParamName = "Param value", ...)`, use the function [get_available_params] for a list of the available filter parameters for a given API endpoint and see the API documentation for their description
#' @param cfg a [config] object describing the configuration of the APIs. Use the internal package configuration by default
#' configuration
#'
......@@ -23,26 +21,26 @@
#' names(cfg$apis)
#'
#' # To get the available endpoints in an API
#' names(cfg$apis[["prelevements"]]$operations)
#' names(cfg$apis[["prelevements"]]$endpoints)
#'
#' # To get available parameters in operation "chroniques" of the API "prelevements"
#' get_available_params(api = "prelevements", operation = "chroniques")
#' # To get available parameters in endpoint "chroniques" of the API "prelevements"
#' get_available_params(api = "prelevements", endpoint = "chroniques")
#'
#' # To query the operation "chroniques" of the API "prelevements"
#' # To query the endpoint "chroniques" of the API "prelevements"
#' # on all devices in the commune of Romilly-sur-Seine in 2018
#' doApiQuery(api = "prelevements",
#' operation = "chroniques",
#' endpoint = "chroniques",
#' params = list(code_commune_insee = "10323", annee = "2018"))
doApiQuery <- function(api,
operation,
endpoint,
params,
cfg = config::get(file = system.file("config.yml", package = "hubeau"))) {
availableParams <- get_available_params(api, operation, cfg)
availableParams <- get_available_params(api, endpoint, cfg)
query <-
file.path(cfg$api_url, cfg$apis[[api]]$path, cfg$apis[[api]]$operations[[operation]]$path)
file.path(cfg$api_url, cfg$apis[[api]]$path, cfg$apis[[api]]$endpoints[[endpoint]]$path)
for (paramName in names(params)) {
if (!paramName %in% cfg$apis[[api]]$operations[[operation]]$fields) {
if (!paramName %in% cfg$apis[[api]]$endpoints[[endpoint]]$fields) {
stop(
sprintf(
"The parameter '%s' is not available for this query. ",
......@@ -52,7 +50,7 @@ doApiQuery <- function(api,
sprintf(
"Run `hubeau::get_available_params(\"%s\", \"%s\")` to get available parameters.",
api,
operation
endpoint
)
)
}
......
......@@ -8,14 +8,14 @@
#' @inherit doApiQuery examples
#'
get_available_params <- function(api,
operation,
endpoint,
cfg = config::get(file = system.file("config.yml",
package = "hubeau"))) {
if (is.null(cfg$apis[[api]])) {
stop("The API '", api, "' is not available on Hub'eau, or is not implemented in the package")
}
if (is.null(cfg$apis[[api]]$operations[[operation]])) {
stop("The operation '", operation, "' is not available for this API, or is not implemented in the package")
if (is.null(cfg$apis[[api]]$endpoints[[endpoint]])) {
stop("The endpoint '", endpoint, "' is not available for this API, or is not implemented in the package")
}
cfg$apis[[api]]$operations[[operation]]$fields
cfg$apis[[api]]$endpoints[[endpoint]]$fields
}
......@@ -47,7 +47,7 @@ get_hydrometrie_obs_elab <- function(params,
package = "hubeau"))) {
l <- doApiQuery(
api = "hydrometrie",
operation = "obs_elab",
endpoint = "obs_elab",
params = params,
cfg = cfg
)
......@@ -68,7 +68,7 @@ get_hydrometrie_observations_tr <- function(params,
l <- doApiQuery(
api = "hydrometrie",
operation = "observations_tr",
endpoint = "observations_tr",
params = params,
cfg = cfg
)
......@@ -101,7 +101,7 @@ get_hydrometrie_sites <- function(params,
package = "hubeau"))) {
l <- doApiQuery(
api = "hydrometrie",
operation = "sites",
endpoint = "sites",
params = params,
cfg = cfg
)
......@@ -148,7 +148,7 @@ get_hydrometrie_sites <- function(params,
get_hydrometrie_stations <- function(params, code_sandre_reseau_station = FALSE, cfg = config::get(file = system.file("config.yml",
package = "hubeau"))) {
l <- doApiQuery(api = "hydrometrie",
operation = "stations",
endpoint = "stations",
params = params,
cfg = cfg)
l <- lapply(l, function(x) {
......
......@@ -67,7 +67,7 @@ get_indicateurs_services_communes <- function(params,
package = "hubeau"))) {
l <- doApiQuery(api = "indicateurs_services",
operation = "communes",
endpoint = "communes",
params = params,
cfg = cfg)
......@@ -85,7 +85,7 @@ get_indicateurs_services_indicateurs <- function(params,
cfg = config::get(file = system.file("config.yml",
package = "hubeau"))) {
l <- doApiQuery(api = "indicateurs_services",
operation = "indicateurs",
endpoint = "indicateurs",
params = params,
cfg = cfg)
......@@ -104,7 +104,7 @@ get_indicateurs_services_services <- function(params,
package = "hubeau"))) {
l <- doApiQuery(api = "indicateurs_services",
operation = "services",
endpoint = "services",
params = params,
cfg = cfg)
......
......@@ -37,7 +37,7 @@
get_niveaux_nappes_stations <- function(params, cfg = config::get(file = system.file("config.yml",
package = "hubeau"))) {
l <- doApiQuery(api = "niveaux_nappes",
operation = "stations",
endpoint = "stations",
params = params,
cfg = cfg)
l <- lapply(l, function(x) {
......@@ -54,7 +54,7 @@ get_niveaux_nappes_chroniques <- function(params,
package = "hubeau"))) {
l <- doApiQuery(
api = "niveaux_nappes",
operation = "chroniques",
endpoint = "chroniques",
params = params,
cfg = cfg
)
......@@ -68,7 +68,7 @@ get_niveaux_nappes_chroniques_tr <- function(params,
package = "hubeau"))) {
l <- doApiQuery(
api = "niveaux_nappes",
operation = "chroniques_tr",
endpoint = "chroniques_tr",
params = params,
cfg = cfg
)
......
......@@ -27,7 +27,7 @@
get_prelevements_points_prelevement <- function(params, cfg = config::get(file = system.file("config.yml",
package = "hubeau"))) {
l <- doApiQuery(api = "prelevements",
operation = "points_prelevement",
endpoint = "points_prelevement",
params = params,
cfg = cfg)
......@@ -39,7 +39,7 @@ get_prelevements_points_prelevement <- function(params, cfg = config::get(file =
get_prelevements_ouvrages <- function(params, cfg = config::get(file = system.file("config.yml",
package = "hubeau"))) {
l <- doApiQuery(api = "prelevements",
operation = "ouvrages",
endpoint = "ouvrages",
params = params,
cfg = cfg)
l <- lapply(l, function(x) {
......@@ -56,7 +56,7 @@ get_prelevements_ouvrages <- function(params, cfg = config::get(file = system.fi
get_prelevements_chroniques <- function(params, cfg = config::get(file = system.file("config.yml",
package = "hubeau"))) {
l <- doApiQuery(api = "prelevements",
operation = "chroniques",
endpoint = "chroniques",
params = params,
cfg = cfg)
l <- lapply(l, function(x) {
......
#' hubeau: A package for retrieving data on the French databases on water "Hub'eau"
#'
#' The 'hubeau' package provides functions for APIs and related "operations". These functions are named as follow: `hubeau::get_[API]_[operation]`.
#' The 'hubeau' package provides functions for "Hub'eau" APIs and their related endpoints.
#' These functions are named as follow: `hubeau::get_[API]_[endpoint]`.
#'
#' Currently available APIs and related "operations" are listed below.
#' Currently available APIs and related endpoints are listed below.
#'
#' **API "Hydrométrie"**
#'
......@@ -10,9 +11,10 @@
#'
#' Available functions:
#'
#' - [get_hydrometrie_observations_tr]: hydrometry water level and discharge time series
#' - [get_hydrometrie_sites]: hydrometry sites (can contain several stations)
#' - [get_hydrometrie_stations]: hydrometry stations
#' - [get_hydrometrie_observations_tr]: hydrometry water level and discharge time series
#' - [get_hydrometrie_obs_elab]: hydrometric elaborate observations (daily/monthly mean flow)
#'
#' **API "Indicateurs des services"**
#'
......
......@@ -3,7 +3,7 @@ default:
apis:
prelevements:
path: v1/prelevements
operations:
endpoints:
points_prelevement:
path: referentiel/points_prelevement
fields:
......@@ -71,7 +71,7 @@ default:
- nom_ouvrage
indicateurs_services:
path: v0/indicateurs_services
operations:
endpoints:
communes:
path: communes
fields:
......@@ -97,7 +97,7 @@ default:
- type_service
hydrometrie:
path: v1/hydrometrie
operations:
endpoints:
stations:
path: referentiel/stations
fields:
......@@ -167,7 +167,7 @@ default:
- resultat_min
niveaux_nappes:
path: v1/niveaux_nappes
operations:
endpoints:
chroniques:
path: chroniques
fields:
......
#' @param params a [list] the list of parameters of the queries and their values in the format `list(ParamName = "Param value", ...)`, use the function [get_available_params] for a list of the available filter parameters for a given operation in an API and see the API documentation for their description
#' @param params a [list] the list of parameters of the queries and their values in the format `list(ParamName = "Param value", ...)`, use the function [get_available_params] for a list of the available query parameters for a given API endpoint and see the API documentation for their descriptions
#' @param cfg a [config] object describing the configuration of the APIs. Use the internal package configuration by default
#' configuration
#'
......
......@@ -2,11 +2,11 @@
% Please edit documentation in R/doApiQuery.R
\name{doApiQuery}
\alias{doApiQuery}
\title{Main internal functions for querying the Hub'eau APIs}
\title{Main internal functions for querying the Hub'eau API endpoints}
\usage{
doApiQuery(
api,
operation,
endpoint,
params,
cfg = config::get(file = system.file("config.yml", package = "hubeau"))
)
......@@ -14,9 +14,9 @@ doApiQuery(
\arguments{
\item{api}{a \link{character} name of the API (e.g.: "indicateurs_services", "prelevements"...), see example for available APIs}
\item{operation}{a \link{character} name of the endpoint, see example for available endpoints in an API}
\item{endpoint}{a \link{character} name of the endpoint, see example for available endpoints in an API}
\item{params}{a \link{list} the list of parameters of the queries and their values in the format \code{list(ParamName = "Param value", ...)}, use the function \link{get_available_params} for a list of the available filter parameters for a given operation in an API and see the API documentation for their description}
\item{params}{a \link{list} the list of parameters of the queries and their values in the format \code{list(ParamName = "Param value", ...)}, use the function \link{get_available_params} for a list of the available filter parameters for a given API endpoint and see the API documentation for their description}
\item{cfg}{a \link{config} object describing the configuration of the APIs. Use the internal package configuration by default
configuration}
......@@ -25,13 +25,11 @@ configuration}
A \link{list} with the concatenated results returned by the API.
}
\description{
The function \code{doQueryApi} is called by all the function querying the APIs and return the raw data sent by the API.
The function \code{doQueryApi} is called by all the function querying the API endpoints and return the raw data sent by the endpoint.
Pagination of the queries is handled automatically and the returned \link{list} is the concatenation of all the results sent by the API.
}
\details{
The function \code{get_available_params} returns the list of available query parameters for a given operation in an API.
The functions \verb{get_[api]_[operation]} call the function \code{doQueryApi} and convert the response in a convenient format for the user (\link{data.frame} or \link[tibble:tibble]{tibble::tibble})
The functions \verb{get_[api]_[endpoint]} call the function \code{doQueryApi} and convert the response in a convenient format for the user (\link{data.frame} or \link[tibble:tibble]{tibble::tibble})
}
\examples{
# To get the available APIs in the package
......@@ -39,14 +37,14 @@ cfg <- config::get(file = system.file("config.yml", package = "hubeau"))
names(cfg$apis)
# To get the available endpoints in an API
names(cfg$apis[["prelevements"]]$operations)
names(cfg$apis[["prelevements"]]$endpoints)
# To get available parameters in operation "chroniques" of the API "prelevements"
get_available_params(api = "prelevements", operation = "chroniques")
# To get available parameters in endpoint "chroniques" of the API "prelevements"
get_available_params(api = "prelevements", endpoint = "chroniques")
# To query the operation "chroniques" of the API "prelevements"
# To query the endpoint "chroniques" of the API "prelevements"
# on all devices in the commune of Romilly-sur-Seine in 2018
doApiQuery(api = "prelevements",
operation = "chroniques",
endpoint = "chroniques",
params = list(code_commune_insee = "10323", annee = "2018"))
}
......@@ -6,14 +6,14 @@
\usage{
get_available_params(
api,
operation,
endpoint,
cfg = config::get(file = system.file("config.yml", package = "hubeau"))
)
}
\arguments{
\item{api}{a \link{character} name of the API (e.g.: "indicateurs_services", "prelevements"...), see example for available APIs}
\item{operation}{a \link{character} name of the endpoint, see example for available endpoints in an API}
\item{endpoint}{a \link{character} name of the endpoint, see example for available endpoints in an API}
\item{cfg}{a \link{config} object describing the configuration of the APIs. Use the internal package configuration by default
configuration}
......@@ -30,14 +30,14 @@ cfg <- config::get(file = system.file("config.yml", package = "hubeau"))
names(cfg$apis)
# To get the available endpoints in an API
names(cfg$apis[["prelevements"]]$operations)
names(cfg$apis[["prelevements"]]$endpoints)
# To get available parameters in operation "chroniques" of the API "prelevements"
get_available_params(api = "prelevements", operation = "chroniques")
# To get available parameters in endpoint "chroniques" of the API "prelevements"
get_available_params(api = "prelevements", endpoint = "chroniques")
# To query the operation "chroniques" of the API "prelevements"
# To query the endpoint "chroniques" of the API "prelevements"
# on all devices in the commune of Romilly-sur-Seine in 2018
doApiQuery(api = "prelevements",
operation = "chroniques",
endpoint = "chroniques",
params = list(code_commune_insee = "10323", annee = "2018"))
}
......@@ -31,7 +31,7 @@ get_hydrometrie_stations(
)
}
\arguments{
\item{params}{a \link{list} the list of parameters of the queries and their values in the format \code{list(ParamName = "Param value", ...)}, use the function \link{get_available_params} for a list of the available filter parameters for a given operation in an API and see the API documentation for their description}
\item{params}{a \link{list} the list of parameters of the queries and their values in the format \code{list(ParamName = "Param value", ...)}, use the function \link{get_available_params} for a list of the available query parameters for a given API endpoint and see the API documentation for their description}
\item{cfg}{a \link{config} object describing the configuration of the APIs. Use the internal package configuration by default
configuration}
......
......@@ -22,7 +22,7 @@ get_indicateurs_services_services(
)
}
\arguments{
\item{params}{a \link{list} the list of parameters of the queries and their values in the format \code{list(ParamName = "Param value", ...)}, use the function \link{get_available_params} for a list of the available filter parameters for a given operation in an API and see the API documentation for their description}
\item{params}{a \link{list} the list of parameters of the queries and their values in the format \code{list(ParamName = "Param value", ...)}, use the function \link{get_available_params} for a list of the available query parameters for a given API endpoint and see the API documentation for their description}
\item{cfg}{a \link{config} object describing the configuration of the APIs. Use the internal package configuration by default
configuration}
......
......@@ -22,7 +22,7 @@ get_niveaux_nappes_chroniques_tr(
)
}
\arguments{
\item{params}{a \link{list} the list of parameters of the queries and their values in the format \code{list(ParamName = "Param value", ...)}, use the function \link{get_available_params} for a list of the available filter parameters for a given operation in an API and see the API documentation for their description}
\item{params}{a \link{list} the list of parameters of the queries and their values in the format \code{list(ParamName = "Param value", ...)}, use the function \link{get_available_params} for a list of the available query parameters for a given API endpoint and see the API documentation for their description}
\item{cfg}{a \link{config} object describing the configuration of the APIs. Use the internal package configuration by default
configuration}
......
......@@ -22,7 +22,7 @@ get_prelevements_chroniques(
)
}
\arguments{
\item{params}{a \link{list} the list of parameters of the queries and their values in the format \code{list(ParamName = "Param value", ...)}, use the function \link{get_available_params} for a list of the available filter parameters for a given operation in an API and see the API documentation for their description}
\item{params}{a \link{list} the list of parameters of the queries and their values in the format \code{list(ParamName = "Param value", ...)}, use the function \link{get_available_params} for a list of the available query parameters for a given API endpoint and see the API documentation for their description}
\item{cfg}{a \link{config} object describing the configuration of the APIs. Use the internal package configuration by default
configuration}
......
......@@ -5,10 +5,11 @@
\alias{hubeau}
\title{hubeau: A package for retrieving data on the French databases on water "Hub'eau"}
\description{
The 'hubeau' package provides functions for APIs and related "operations". These functions are named as follow: \verb{hubeau::get_[API]_[operation]}.
The 'hubeau' package provides functions for "Hub'eau" APIs and their related endpoints.
These functions are named as follow: \verb{hubeau::get_[API]_[endpoint]}.
}
\details{
Currently available APIs and related "operations" are listed below.
Currently available APIs and related endpoints are listed below.
\strong{API "Hydrométrie"}
......@@ -16,9 +17,10 @@ API documentation: \url{https://hubeau.eaufrance.fr/page/api-hydrometrie}
Available functions:
\itemize{
\item \link{get_hydrometrie_observations_tr}: hydrometry water level and discharge time series
\item \link{get_hydrometrie_sites}: hydrometry sites (can contain several stations)
\item \link{get_hydrometrie_stations}: hydrometry stations
\item \link{get_hydrometrie_observations_tr}: hydrometry water level and discharge time series
\item \link{get_hydrometrie_obs_elab}: hydrometric elaborate observations (daily/monthly mean flow)
}
\strong{API "Indicateurs des services"}
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment