|
| 1 | +#' |
| 2 | +#' Get information on various ICD 11 Foundation entities |
| 3 | +#' |
| 4 | +#' @param base_url The base URL of the API. Default uses the WHO API server at |
| 5 | +#' https://id.who.int. If you are using a locally deployed server or hosting |
| 6 | +#' your own ICD API server, you should specify the URL of your instance here. |
| 7 | +#' @param client The OAuth2 client produced through a call to `icd_oauth_client()`. |
| 8 | +#' @param scope Scopes to be requested from the resource owner. Default is |
| 9 | +#' *"icdapi_access"* as specified in the ICD API documentation. |
| 10 | +#' @param id Unique numerical identifier for an entity. |
| 11 | +#' @param release A string specifying the release version of the Foundation to |
| 12 | +#' search from. If not specified, defaults to the latest release version. See |
| 13 | +#' the available versions with `icd_versions`. |
| 14 | +#' @param include A string or a vector of strings for optional property values |
| 15 | +#' to be included in the response. The property values that can be included |
| 16 | +#' are *"ancestor"*, *"descendant"*, or *"diagnosticCriteria"*. If not |
| 17 | +#' specified, these properties are not included in the response. |
| 18 | +#' @param api_version Version of the API. Possible values are `v1` or `v2`. |
| 19 | +#' For example, if you provide value v2, the API will respond in the format of |
| 20 | +#' the version 2 of the API. Default is `v2`. |
| 21 | +#' @param language ICD-API is multi-lingual. By changing this header, you may |
| 22 | +#' make the API respond in different languages. Languages will be available as |
| 23 | +#' the translations of ICD-11 completes. The values are language codes such as |
| 24 | +#' en, es, zh, etc. Depending on the `release_id` specified, the available |
| 25 | +#' languages will vary. Default is English ("en"). |
| 26 | +#' @param parse Logical. Should JSON response body be parsed? Default is |
| 27 | +#' TRUE. If FALSE, response body is kept as raw JSON. |
| 28 | +#' |
| 29 | +#' @return A list or JSON (depending on `parse`) with information on specified |
| 30 | +#' ICD 11 Foundation and top level entities |
| 31 | +#' |
| 32 | +#' @examples |
| 33 | +#' icd_get_foundation() |
| 34 | +#' icd_get_entity(id = "1112016389") |
| 35 | +#' |
| 36 | +#' @rdname icd_get |
| 37 | +#' @export |
| 38 | +#' |
| 39 | +icd_get_foundation <- function(base_url = "https://id.who.int", |
| 40 | + client = icd_oauth_client(), |
| 41 | + scope = "icdapi_access", |
| 42 | + release = NULL, |
| 43 | + api_version = c("v2", "v1"), |
| 44 | + language = "en", |
| 45 | + parse = TRUE) { |
| 46 | + ## Get API version to use ---- |
| 47 | + api_version <- match.arg(api_version) |
| 48 | + |
| 49 | + ## Make request ---- |
| 50 | + req <- httr2::request(file.path(base_url, "icd/entity")) |> |
| 51 | + httr2::req_headers( |
| 52 | + Accept = "application/json", |
| 53 | + "API-Version" = api_version, |
| 54 | + "Accept-Language" = language |
| 55 | + ) |> |
| 56 | + ## Authenticate ---- |
| 57 | + icd_authenticate(client = client, scope = scope) |> |
| 58 | + ## Perform request ---- |
| 59 | + httr2::req_perform() |
| 60 | + |
| 61 | + ## Determine what output to return ---- |
| 62 | + if (parse) { |
| 63 | + ### Parse JSON and simplify ---- |
| 64 | + resp <- req |> |
| 65 | + httr2::resp_body_json() |
| 66 | + } else { |
| 67 | + ### Keep as JSON ---- |
| 68 | + resp <- req |> |
| 69 | + httr2::resp_body_raw() |
| 70 | + } |
| 71 | + |
| 72 | + ## Return response body ---- |
| 73 | + resp |
| 74 | +} |
| 75 | + |
| 76 | + |
| 77 | +#' |
| 78 | +#' @rdname icd_get |
| 79 | +#' @export |
| 80 | +#' |
| 81 | +icd_get_entity <- function(base_url = "https://id.who.int", |
| 82 | + client = icd_oauth_client(), |
| 83 | + scope = "icdapi_access", |
| 84 | + id, |
| 85 | + release = NULL, |
| 86 | + include = NULL, |
| 87 | + api_version = c("v2", "v1"), |
| 88 | + language = "en", |
| 89 | + parse = TRUE) { |
| 90 | + ## Get API version to use ---- |
| 91 | + api_version <- match.arg(api_version) |
| 92 | + |
| 93 | + ## Make base request ---- |
| 94 | + req <- httr2::request(file.path(base_url, "icd/entity", id)) |> |
| 95 | + httr2::req_headers( |
| 96 | + Accept = "application/json", |
| 97 | + "API-Version" = api_version, |
| 98 | + "Accept-Language" = language |
| 99 | + ) |
| 100 | + |
| 101 | + ## Add optional queries ---- |
| 102 | + |
| 103 | + ### Add releaseId ---- |
| 104 | + if (!is.null(release)) { |
| 105 | + req <- req |> |
| 106 | + httr2::req_url_query(releaseId = release) |
| 107 | + } |
| 108 | + |
| 109 | + ### Add include ---- |
| 110 | + if (!is.null(include)) { |
| 111 | + include <- paste(include, collapse = ",") |
| 112 | + |
| 113 | + req <- req |> |
| 114 | + httr2::req_url_query(include = include) |
| 115 | + } |
| 116 | + |
| 117 | + ## Authenticate request ---- |
| 118 | + req <- req |> |
| 119 | + icd_authenticate(client = client, scope = "icdapi_access") |> |
| 120 | + ## Perform request ---- |
| 121 | + httr2::req_perform() |
| 122 | + |
| 123 | + ## Determine what output to return ---- |
| 124 | + if (parse) { |
| 125 | + ### Parse JSON and simplify ---- |
| 126 | + resp <- req |> |
| 127 | + httr2::resp_body_json() |
| 128 | + } else { |
| 129 | + ### Keep as JSON ---- |
| 130 | + resp <- req |> |
| 131 | + httr2::resp_body_raw() |
| 132 | + } |
| 133 | + |
| 134 | + ## Return response body ---- |
| 135 | + resp |
| 136 | +} |
0 commit comments