-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.Rmd
158 lines (92 loc) · 4.35 KB
/
README.Rmd
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
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
---
title: "clubhouser"
output: github_document
editor_options:
chunk_output_type: console
---
[](https://travis-ci.org/SymbolixAU/clubhouser) [](https://codecov.io/gh/SymbolixAU/clubhouser)
[](https://cran.r-project.org/package=clubhouser)
```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#",
fig.path = "man/figures/README-",
out.width = "100%",
out.height = 200
)
```
```{r, include=FALSE}
library(clubhouser)
library(httptest)
.mockPaths("tests/testthat/")
start_vignette("./")
```
A simple API wrapper library for accessing the [https://clubhouse.io/](https://clubhouse.io/) API.
By default, the package returns queries from the V2 API - full documentation can be found here [https://api.clubhouse.io/api/v2](https://api.clubhouse.io/api/v2).
## Installing
<!-- If you're putting `clubhouser` on CRAN, it can be installed with
install.packages("clubhouser") -->
The pre-release version of the package can be pulled from GitHub using the [devtools](https://github.com/r-lib/devtools) package:
# install.packages("devtools")
devtools::install_github("SymbolixAU/clubhouser")
## What else do I need?
You need an access token to retrieve and put records into Clubhouse.
If you / your team has a Clubhouse account, bring up the Settings menu (top right) and select "API tokens" from the list on the left.
Download and save it somewhere safe. I recommend adding it to your .Rprofile and retrieving it with `Sys.getenv("CH_TOKEN")`
If your team doesn't use Clubhouse.....I can't help you. If you are an agile team it's worth a look - it's more structured than Trello and much more user friendly than Jira. And, no they haven't given me any money (though, if someone is offering....)
## Setting up
### Telling `clubhouser` about your API token
You can send your token as an argument to the API functions.
If you are a little ~~lazy~~ efficient you can also use one of the package's convenience functions to set it once for all subsequent API calls to use.
To set:
```{r, eval = FALSE}
set_token("mysecrettoken")
```
To retrieve your token (if needed):
```{r, eval=FALSE}
get_token()
```
### Changing the API version
By default, the package returns queries from the V2 API but you can override this on a function-by-function basis by setting the `url` parameter. You can also change the default. For example, if you want to be brave and use the latest, beta version you would:
```{r, eval=FALSE}
set_url(url = "https://clubhouse.io/api/beta")
```
### Reset defaults
To reset the API settings to their defaults (i.e. clear the stored token and reset to V2 of the API), simply:
```{r, eval=FALSE}
reset_api()
```
---
## 'GET'ting records
You can list all the records for a single API endpoint (`ch_list_all`), or you can retrieve a single record (`ch_get_one`).
### `ch_list_all`
You can list all records from the following endpoints
>> "categories", "epic-workflow", "epics", "files", "labels", "linked-files", "members",
"milestones", "projects", "repositories", "stories","teams", "workflows"
You can pull back all the details:
```{r, eval=TRUE}
library(clubhouser)
set_token("foo")
ch_list_all(endpoint = "categories",response_type = "full")
```
Or just a minimal set (useful if you just want to filter and get an `id` or two so you can retrieve just those records).
```{r, eval=TRUE}
ch_list_all(endpoint = "categories",response_type = "minimal")
```
### Return one record
If you know the `id` of the record you want to retrieve you can get that record. If I want to get the full information about the Story with `id` 123, it's as simple as:
```{r}
# This returns a list object with all the story details
res <- ch_get_one(id = 123L, endpoint = "stories")
# From here you can access the tasks on the Story card
res$tasks
# Or the point estimate
res$estimate
# or the description
res$description
#....you get the idea
```
## Next tasks
Currently the package only contains GET functions. The next step is to add in the ability to create, update and delete records. I'll track progress in the Issues tab.