kthapi/README.Rmd at master · KTH-Library/kthapi · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# kthapi

<!-- badges: start -->
[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://www.tidyverse.org/lifecycle/#experimental)
[![R-CMD-check](https://github.com/KTH-Library/kthapi/workflows/R-CMD-check/badge.svg)](https://github.com/KTH-Library/kthapi/actions)
[![R-CMD-check](https://github.com/KTH-Library/kthapi/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/KTH-Library/kthapi/actions/workflows/R-CMD-check.yaml)
<!-- badges: end -->

The goal of the `kthapi` R package is to provide an API wrapper for some of the APIs used at KTH, The Royal Institute of Technology, which can be used directly in R.

The KTH APIs are described here:

<https://www.kth.se/api/anvand-data-fran-kth-1.57059>

The KTH APIs provide information about employee profiles, published web content, places, course schemas and program catalogues. This R package interfaces with the API, making data available to use directly from R.

## Installation

You can install the development version of kthapi from GitHub with:

``` r
#install.packages("devtools)
devtools::install_github("KTH-Library/kthapi", dependencies = TRUE)
```

## Example usage

This API wrapper / client is pre-configured with a set of API endpoints:

```{r example}
library(kthapi)
library(knitr)
suppressPackageStartupMessages(library(dplyr))
```

This is a basic example which shows you how to make a lookup using the "legacy" Profiles API, where we get contact information for a KTH employee using an account name:

```{r}

profile <-
  kth_profile_legacy(userid = "tjep") |>
  getElement("content")

# inspect this record
profile |> glimpse()

# pivot into long format and display as a table
profile %>% t() %>% as.data.frame() %>%
  cbind(rownames(.)) %>% setNames(nm = c("value", "key")) %>% as_tibble() %>%
  select(key, value) %>%
  kable()


# NB: some valid account names do not return data
tryCatch(kth_profile_legacy("hoyce"), error = function(e) e)
```

## More examples

This is a basic example which shows how to make a lookup using the authenticated Profiles API:

```{r}

profile <-
  kth_profile(username = "tjep") |>
  _$content

# organizational belonging
profile$worksFor$items |>
  tibble::as_tibble() |>
  select(key, name, nameEn) |>
  mutate(slug = kthapi:::path_worksFor(key)) |>
  knitr::kable()

# displayname used in ABM app
kth_displayname("tjep", type = "username")

# NB: this (authenticated API call) does not throw an error for non-employees
kth_displayname("markussk", type = "username")

```

For more usage examples, please see the package vignettes.