Skip to content

Commit 1542472

Browse files
ernestguevarraernestguevarra
authored
Merge pull request #11 from OxfordIHTM/dev
add all search query parameters to search function
2 parents d70c0d1 + b020da6 commit 1542472

33 files changed

+107935
-240
lines changed

‎DESCRIPTION

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,11 +18,13 @@ License: GPL (>= 3)
1818
Depends:
1919
R (>= 2.10)
2020
Imports:
21-
httr
21+
httr,
22+
httr2
2223
Suggests:
2324
covr,
2425
httpuv,
25-
spelling
26+
spelling,
27+
tibble
2628
Encoding: UTF-8
2729
LazyData: true
2830
Language: en-GB

‎NAMESPACE

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,13 @@
11
# Generated by roxygen2: do not edit by hand
22

3-
export(icd_endpoint)
4-
export(icd_oauth_app)
5-
export(icd_token)
3+
export(icd_oauth_client)
4+
export(icd_search_foundation)
65
importFrom(httr,oauth2.0_token)
76
importFrom(httr,oauth_app)
87
importFrom(httr,oauth_endpoint)
8+
importFrom(httr2,oauth_client)
9+
importFrom(httr2,req_headers)
10+
importFrom(httr2,req_oauth_client_credentials)
11+
importFrom(httr2,req_perform)
12+
importFrom(httr2,req_url_query)
13+
importFrom(httr2,request)

‎R/icd.R

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,5 +12,7 @@
1212
#' @keywords internal
1313
#' @name icd
1414
#' @importFrom httr oauth2.0_token oauth_app oauth_endpoint
15+
#' @importFrom httr2 oauth_client request req_url_query req_headers
16+
#' req_oauth_client_credentials req_perform
1517
#'
1618
"_PACKAGE"

‎R/icd_authenticate.R

Lines changed: 18 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -1,77 +1,37 @@
11
#'
22
#' OAuth2 authentication to ICD API
33
#'
4-
#' @param authorize url to send client to for authorisation. Set to NULL if not
5-
#' needed.
6-
#' @param access url used to exchange unauthenticated for authenticated token.
7-
#' @param endpoint OAuth endpoint for the ICD API, created by `icd_endpoint()`
8-
#' @param app An OAuth consumer application, created by `icd_oauth_app()` by
9-
#' default.
10-
#' @param scope ICD API scope to request. Default is "icdapi_access".
11-
#' @param as_header If TRUE, the default, configures the token to add itself to
12-
#' the bearer header of subsequent requests. If FALSE, configures the token to
13-
#' add itself as a url parameter of subsequent requests.
14-
#' @param client_credentials Default to FALSE. Set to TRUE to use Client
15-
#' Credentials Grant instead of Authorization Code Grant. See
16-
#' https://www.rfc-editor.org/rfc/rfc6749#section-4.4.
17-
#' @param ... Other parameters/arguments to be passed onto `httr::oauth2.0_token()`
18-
#' @param appname Name of the application. This is not used for OAuth, but is
19-
#' used to make it easier to identify different applications.
20-
#' @param key Consumer key, also sometimes called the client ID.
4+
#' @param id Consumer key, also sometimes called the client ID.
5+
#' @param token_url url used to exchange unauthenticated for authenticated token.
216
#' @param secret Consumer secret, also sometimes called the client secret.
227
#' Despite its name, this does not necessarily need to be protected like a
238
#' password, i.e. the user still has to authenticate themselves and grant the
249
#' app permission to access resources on their behalf.
10+
#' @param name Name of the application. This is not used for OAuth, but is
11+
#' used to make it easier to identify different applications.
12+
#' @param ... Other parameters/arguments to be passed onto `httr2::oauth_client()`
2513
#'
26-
#' @return For `icd_token()`, a Token2.0 reference class (RC) object.
14+
#' @return An `httr2_oauth_client` class (RC) object.
2715
#'
2816
#' @examples
29-
#' icd_endpoint()
30-
#' icd_token()
31-
#' icd_oauth_app()
32-
#'
33-
#' @rdname icd_authenticate
34-
#'
35-
#' @export
36-
#'
37-
icd_endpoint <- function(authorize = NULL,
38-
access = "https://icdaccessmanagement.who.int/connect/token") {
39-
httr::oauth_endpoint(authorize = authorize, access = access)
40-
}
41-
17+
#' icd_oauth_client()
4218
#'
4319
#' @rdname icd_authenticate
44-
#' @export
45-
#'
46-
icd_oauth_app <- function(appname = "icd_app",
47-
key = "6fc8a1e4-4da9-43a8-bd0c-c164c0cb0ebd_3c7e272e-2f4b-46de-b127-df7454e36be8",
48-
secret = "OGIly8mTatQ2ILuhBTbviIp2FofWiQR3fj4HaPiGseE=") {
49-
httr::oauth_app(
50-
appname = appname,
51-
key = key,
52-
secret = secret
53-
)
54-
}
55-
5620
#'
57-
#' @rdname icd_authenticate
5821
#' @export
5922
#'
60-
icd_token <- function(endpoint = icd_endpoint(),
61-
app = icd_oauth_app(),
62-
scope = "icdapi_access",
63-
as_header = TRUE,
64-
client_credentials = TRUE, ...) {
65-
httr::oauth2.0_token(
66-
endpoint = endpoint,
67-
app = app,
68-
scope = scope,
69-
#use_oob = use_oob,
70-
as_header = as_header,
71-
client_credentials = client_credentials,
72-
...
23+
icd_oauth_client <- function(id = "6fc8a1e4-4da9-43a8-bd0c-c164c0cb0ebd_3c7e272e-2f4b-46de-b127-df7454e36be8",
24+
token_url = "https://icdaccessmanagement.who.int/connect/token",
25+
secret = "OGIly8mTatQ2ILuhBTbviIp2FofWiQR3fj4HaPiGseE=",
26+
name = "icd_client",
27+
...) {
28+
httr2::oauth_client(
29+
id = id,
30+
token_url = token_url,
31+
secret = secret,
32+
auth = "header",
33+
name = name
7334
)
7435
}
7536

7637

77-

‎R/icd_search.R

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
#'
2+
#' Search the foundation component of the ICD-11
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 q String. Text to be searched. Having the character `%` at the end will
9+
#' be regarded as a wild card for that word.
10+
#' @param subtree A string or vector of strings of URIs. If provided, the
11+
#' search will be performed on the entities provided and their descendants.
12+
#' @param chapter A string or vector of strings of chapter codes
13+
#' eg: c("01", "02") When provided, the search will be performed only on
14+
#' these chapters.
15+
#' @param flexisearch Logical. Default is FALSE. Changes the search mode to
16+
#' flexible search. In the regular search mode, the Coding Tool will only give
17+
#' you results that contain all of the words that you've used in your search.
18+
#' It accepts different variants or synonyms of the words but essentially it
19+
#' searches for a result that contains all components of your search. Whereas
20+
#' in flexible search mode, the results do not have to contain all of the words
21+
#' that are typed. It would still try to find the best matching phrase but
22+
#' there may be words in your search that are not matched at all. It is
23+
#' recommended to use flexible search only when regular search does not
24+
#' provide a result.
25+
#' @param flat Logical. Default is FALSE. If set to true the search result
26+
#' entities are provided in a nested data structure representing the
27+
#' ICD-11 hierarchy. Otherwise they are listed as flat list of matches.
28+
#' @param properties A string or a vector of strings for the properties to be
29+
#' searched. By default the system searches, *"Title"*, *"Synonyms"*, and
30+
#' *"FullySpecifiedName"*. The valid values that could be used are: *Title"*,
31+
#' *"Synonym"*, *"NarrowerTerm"*, *"FullySpecifiedName"*, *"Definition"*, and
32+
#' *"Exclusion"*.
33+
#' @param release A string specifying the release version of the Foundation to
34+
#' search from. If not specified, defaults to the latest release version. See
35+
#' the available versions with `icd_versions`.
36+
#' @param highlight Logical. Default is FALSE. If set to FALSE the search result
37+
#' highlighting is turned off and the results don't contain special tags for
38+
#' highlighting where the results are found within the text.
39+
#' @param api_version Version of the API. Possible values are `v1` or `v2`.
40+
#' For example, if you provide value v2, the API will respond in the format of
41+
#' the version 2 of the API. Default is `v2`.
42+
#' @param language ICD-API is multi-lingual. By changing this header, you may
43+
#' make the API respond in different languages. Languages will be available as
44+
#' the translations of ICD-11 completes. The values are language codes such as
45+
#' en, es, zh, etc. Depending on the `release_id` specified, the available
46+
#' languages will vary. Default is English ("en").
47+
#'
48+
#' @return An `httr2_response` object
49+
#'
50+
#' @examples
51+
#' icd_search_foundation(q = "cholera")
52+
#'
53+
#' @rdname icd_search
54+
#' @export
55+
#'
56+
57+
icd_search_foundation <- function(base_url = "https://id.who.int",
58+
client = icd_oauth_client(),
59+
q,
60+
subtree = NULL,
61+
chapter = NULL,
62+
flexisearch = FALSE,
63+
flat = TRUE,
64+
properties = NULL,
65+
release = NULL,
66+
highlight = FALSE,
67+
api_version = c("v2", "v1"),
68+
language = "en") {
69+
## Get API version to use ----
70+
api_version <- match.arg(api_version)
71+
72+
## Make base request ----
73+
req <- httr2::request(file.path(base_url, "icd/entity/search")) |>
74+
httr2::req_url_query(q = q)
75+
76+
## Add query components ----
77+
78+
### Subtrees filter ----
79+
if (!is.null(subtree)) {
80+
req <- req |>
81+
httr2::req_url_query(subtreesFilter = paste(subtree, collapse = ","))
82+
}
83+
84+
### Chapters filter ----
85+
if (!is.null(chapter)) {
86+
req <- req |>
87+
httr2::req_url_query(chapterFilter = paste(chapter, collapse = ","))
88+
}
89+
90+
### Flexi search and flatResults component ----
91+
req <- req |>
92+
httr2::req_url_query(
93+
useFlexisearch = ifelse(flexisearch, "true", "false"),
94+
flatResults = ifelse(flat, "true", "false")
95+
)
96+
97+
### Properties ----
98+
if (!is.null(properties)) {
99+
req <- req |>
100+
httr2::req_url_query(
101+
propertiesToBeSearched = paste(properties, collapse = ",")
102+
)
103+
}
104+
105+
### Release ID ----
106+
if (!is.null(release)) {
107+
req <- req |>
108+
httr2::req_url_query(releaseId = release)
109+
}
110+
111+
### Highlighting ----
112+
req <- req |>
113+
httr2::req_url_query(
114+
highlightingEnabled = ifelse(highlight, "true", "false")
115+
)
116+
117+
## Add headers ----
118+
req <- req |>
119+
httr2::req_headers(
120+
Accept = "application/json",
121+
"API-Version" = api_version,
122+
"Accept-Language" = language
123+
) |>
124+
## Authenticate ----
125+
httr2::req_oauth_client_credentials(
126+
client = client,
127+
scope = "icdapi_access"
128+
) |>
129+
## Perform request ----
130+
httr2::req_perform()
131+
}
132+
133+

‎R/utils.R

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
#'
2+
#'
3+
#'
4+
#'
5+
#'
6+
#'

‎README.Rmd

Lines changed: 13 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ The [International Classification of Diseases (ICD)](https://www.who.int/standar
2828

2929
## What does `icd` do?
3030

31-
Please note that `icd` is still highly experimental and is undergoing a lot of development. Hence, any functionalities described below have a high likelihood of changing interface or approach as we approach a stable working version.
31+
Please note that `icd` is still highly experimental and is undergoing a lot of development. Hence, any functionalities described below have a high likelihood of changing interface or approach as we aim for a stable working version.
3232

3333
Currently, the package provides functions for authenticating with the ICD API. From here, the plan is to develop functions that wrap the various available [API endpoints](https://id.who.int/swagger/index.html).
3434

@@ -54,33 +54,32 @@ library(icd)
5454

5555
### Authenticating with the ICD API
5656

57-
The ICD API uses OAuth2 for authentication. The package has a set of utility functions that support the ICD API authentication specifications leading to the generation of an OAuth2 token. The `icd_token()` function is the downstream and user-facing function that creates an ICD OAuth2 token that can be used by future functions that wrap ICD API for entity and linearization information retrieval.
57+
The ICD API uses OAuth2 for authentication. The package has a set of utility functions that support the ICD API authentication specifications leading to the generation of an OAuth2 token. The `icd_oauth_client()` function is the downstream and user-facing function that creates an ICD OAuth2 client that can be used for token retrieval by future functions that wrap ICD API for entity and linearization information retrieval.
5858

59-
An ICD OAuth2 token can be generated as follows:
59+
An ICD OAuth2 client can be generated as follows:
6060

6161
```R
62-
icd_token()
62+
icd_oauth_client()
6363
```
6464

65-
This function uses a built in OAuth2 application created for light use and for purposes of package development and testing.
65+
This function uses a built in OAuth2 client created for light use and for purposes of package development and testing.
6666

6767
It is recommended that those intending to use this package for programmatically performing high volume of calls to the ICD API to create their own **access keys** (`client id` and `client secret`) using [these instructions](https://icd.who.int/docs/icd-api/API-Authentication/).
6868

6969
Then, with your access keys, perform the following commands:
7070

71-
7271
```R
73-
## Create your own OAuth application ----
74-
my_app <- icd_oauth_app(
75-
appname = "NAME_OF_YOUR_APP",
76-
key = "YOUR_CLIEND_ID",
77-
secret = "YOUR_CLIENT_SECRET"
72+
## Create your own OAuth client ----
73+
my_oauth_client <- icd_oauth_client(
74+
id = "YOUR_CLIENT_ID",
75+
token_url = "https://icdaccessmanagement.who.int/connect/token",
76+
secret = "YOUR_CLIENT_SECRET",
77+
name = "NAME_OF_YOUR_APP
7878
)
79-
80-
## Create authentication token ----
81-
my_token <- icd_token(app = my_app)
8279
```
8380
81+
This OAuth2 client can now be used to the various functions in the package that require an OAuth2 client for authentication for making requests to the ICD API.
82+
8483
## Citation
8584
8685
If you find the `icd` package useful please cite using the suggested citation provided by a call to the `citation()` function as follows:

‎README.md

Lines changed: 20 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -30,8 +30,8 @@ interface with the ICD API.
3030

3131
Please note that `icd` is still highly experimental and is undergoing a
3232
lot of development. Hence, any functionalities described below have a
33-
high likelihood of changing interface or approach as we approach a
34-
stable working version.
33+
high likelihood of changing interface or approach as we aim for a stable
34+
working version.
3535

3636
Currently, the package provides functions for authenticating with the
3737
ICD API. From here, the plan is to develop functions that wrap the
@@ -63,19 +63,19 @@ library(icd)
6363

6464
The ICD API uses OAuth2 for authentication. The package has a set of
6565
utility functions that support the ICD API authentication specifications
66-
leading to the generation of an OAuth2 token. The `icd_token()` function
67-
is the downstream and user-facing function that creates an ICD OAuth2
68-
token that can be used by future functions that wrap ICD API for entity
69-
and linearization information retrieval.
66+
leading to the generation of an OAuth2 token. The `icd_oauth_client()`
67+
function is the downstream and user-facing function that creates an ICD
68+
OAuth2 client that can be used for token retrieval by future functions
69+
that wrap ICD API for entity and linearization information retrieval.
7070

71-
An ICD OAuth2 token can be generated as follows:
71+
An ICD OAuth2 client can be generated as follows:
7272

7373
``` r
74-
icd_token()
74+
icd_oauth_client()
7575
```
7676

77-
This function uses a built in OAuth2 application created for light use
78-
and for purposes of package development and testing.
77+
This function uses a built in OAuth2 client created for light use and
78+
for purposes of package development and testing.
7979

8080
It is recommended that those intending to use this package for
8181
programmatically performing high volume of calls to the ICD API to
@@ -86,17 +86,19 @@ instructions](https://icd.who.int/docs/icd-api/API-Authentication/).
8686
Then, with your access keys, perform the following commands:
8787

8888
``` r
89-
## Create your own OAuth application ----
90-
my_app <- icd_oauth_app(
91-
appname = "NAME_OF_YOUR_APP",
92-
key = "YOUR_CLIEND_ID",
93-
secret = "YOUR_CLIENT_SECRET"
89+
## Create your own OAuth client ----
90+
my_oauth_client <- icd_oauth_client(
91+
id = "YOUR_CLIENT_ID",
92+
token_url = "https://icdaccessmanagement.who.int/connect/token",
93+
secret = "YOUR_CLIENT_SECRET",
94+
name = "NAME_OF_YOUR_APP
9495
)
95-
96-
## Create authentication token ----
97-
my_token <- icd_token(app = my_app)
9896
```
9997
98+
This OAuth2 client can now be used to the various functions in the
99+
package that require an OAuth2 client for authentication for making
100+
requests to the ICD API.
101+
100102
## Citation
101103
102104
If you find the `icd` package useful please cite using the suggested

‎data-raw/icd-mapping.zip

6.49 MB
Binary file not shown.

0 commit comments

Comments
 (0)