Update README with path functionality. (#49)

* Update README with path functionality.

* Use methods!

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: beekeeper
 Title: Rapidly Scaffold API Client Packages
-Version: 0.2.0.9000
+Version: 0.3.0.9000
 Authors@R: c(
     person("Jon", "Harmon", , "[email protected]", role = c("aut", "cre", "cph"),
            comment = c(ORCID = "0000-0003-4781-4346")),

R/generate_pkg-paths.R

@@ -65,7 +65,8 @@ S7::method(as_bk_data, class_paths) <- function(x) {
         endpoints$operation
       ),
       description = .paths_fill_descriptions(endpoints$description),
-      params_df = endpoints$parameters
+      params_df = endpoints$parameters,
+      method = endpoints$operation
     ),
     .paths_endpoint_to_list
   )
@@ -91,12 +92,14 @@ S7::method(as_bk_data, class_paths) <- function(x) {
                                     path,
                                     summary,
                                     description,
-                                    params_df) {
+                                    params_df,
+                                    method) {
   params_df <- .prepare_paths_df(params_df)
   return(
     list(
       operation_id = operation_id,
       path = .path_as_arg(path, params_df),
+      method = method,
       summary = summary,
       description = description,
       params = .params_to_list(params_df),

R/paths-apis.R

@@ -0,0 +1,102 @@
+# These functions were generated by the {beekeeper} package, based on the paths
+# element from the source API description. You should carefully review these
+# functions. Missing documentation is tagged with "BKTODO" to make it easier for
+# you to search for issues.
+
+#' List all APIs
+#'
+#' List all APIs in the directory. Returns links to the OpenAPI definitions for each API in the directory. If API exist in multiple versions `preferred` one is explicitly marked. Some basic info from the OpenAPI definition is cached inside each object. This allows you to generate some simple views without needing to fetch the OpenAPI definition for each API.
+#'
+#' @return BKTODO: Return descriptions are not yet implemented in beekeeper
+#' @export
+guru_list_apis <- function() {
+  guru_call_api(
+    path = "/list.json",
+    method = "get"
+  )
+}
+
+#' Get basic metrics
+#'
+#' Some basic metrics for the entire directory. Just stunning numbers to put on a front page and are intended purely for WoW effect :)
+#'
+#' @return BKTODO: Return descriptions are not yet implemented in beekeeper
+#' @export
+guru_get_metrics <- function() {
+  guru_call_api(
+    path = "/metrics.json",
+    method = "get"
+  )
+}
+
+#' List all providers
+#'
+#' List all the providers in the directory
+#'
+#' @return BKTODO: Return descriptions are not yet implemented in beekeeper
+#' @export
+guru_get_providers <- function() {
+  guru_call_api(
+    path = "/providers.json",
+    method = "get"
+  )
+}
+
+#' Retrieve one version of a particular API
+#'
+#' Returns the API entry for one specific version of an API where there is no serviceName.
+#'
+#' @param provider BKTODO: No description provided.
+#' @param api BKTODO: No description provided.
+#' @return BKTODO: Return descriptions are not yet implemented in beekeeper
+#' @export
+guru_get_api <- function(provider, api) {
+  guru_call_api(
+    path = c("/specs/{provider}/{api}.json", provider = provider, api = api),
+    method = "get"
+  )
+}
+
+#' Retrieve one version of a particular API with a serviceName.
+#'
+#' Returns the API entry for one specific version of an API where there is a serviceName.
+#'
+#' @param provider BKTODO: No description provided.
+#' @param service BKTODO: No description provided.
+#' @param api BKTODO: No description provided.
+#' @return BKTODO: Return descriptions are not yet implemented in beekeeper
+#' @export
+guru_get_service_api <- function(provider, service, api) {
+  guru_call_api(
+    path = c("/specs/{provider}/{service}/{api}.json", provider = provider, service = service, api = api),
+    method = "get"
+  )
+}
+
+#' List all APIs for a particular provider
+#'
+#' List all APIs in the directory for a particular providerName Returns links to the individual API entry for each API.
+#'
+#' @param provider BKTODO: No description provided.
+#' @return BKTODO: Return descriptions are not yet implemented in beekeeper
+#' @export
+guru_get_provider <- function(provider) {
+  guru_call_api(
+    path = c("/{provider}.json", provider = provider),
+    method = "get"
+  )
+}
+
+#' List all serviceNames for a particular provider
+#'
+#' List all serviceNames in the directory for a particular providerName
+#'
+#' @param provider BKTODO: No description provided.
+#' @return BKTODO: Return descriptions are not yet implemented in beekeeper
+#' @export
+guru_get_services <- function(provider) {
+  guru_call_api(
+    path = c("/{provider}/services.json", provider = provider),
+    method = "get"
+  )
+}

README.Rmd

@@ -48,10 +48,10 @@ Most of the outline was included in the grant proposal.
     - [x] Add support for APIs using the OAS json format.
     - [x] Streamline discovery of API definitions (with associated error handling).
         -   **UPDATE:** This functionality is in a separate package, [{anyapi}](https://anyapi.api2r.org).
-- [ ] **0.3.0: Endpoint function scaffolding.**
-    - [ ] Generate R/*.R and tests/testthat/*.R files for all endpoints ("paths") described in the given API specification. 
-    - [ ] The generated functions will work, but error checking, documentation, and tests will be minimal.
-    - [ ] **Potential challenges:** I'll need to strike a balance here between getting a basic working system and producing something that can be easily expanded later.
+- [x] **0.3.0: Endpoint function scaffolding.**
+    - [x] Generate R/*.R and tests/testthat/*.R files for all endpoints ("paths") described in the given API specification. 
+    - [x] The generated functions will work, but error checking, documentation, and tests will be minimal.
+    - [x] **Potential challenges:** I'll need to strike a balance here between getting a basic working system and producing something that can be easily expanded later.
         -   **Update:** Also, this likely could go unsaid, but, if the API description is incorrect, the functions will not work as expected. Hopefully their error messages will be helpful for debugging, though!
 - [ ] **0.4.0: Batching and rate limiting.**
     - [ ] Add documentation for implementing batching and rate-limiting. 

README.md

@@ -59,12 +59,12 @@ included in the grant proposal.
     handling).
     - **UPDATE:** This functionality is in a separate package,
       [{anyapi}](https://anyapi.api2r.org).
-- [ ] **0.3.0: Endpoint function scaffolding.**
-  - [ ] Generate R/*.R and tests/testthat/*.R files for all endpoints
+- [x] **0.3.0: Endpoint function scaffolding.**
+  - [x] Generate R/*.R and tests/testthat/*.R files for all endpoints
     (“paths”) described in the given API specification.
-  - [ ] The generated functions will work, but error checking,
+  - [x] The generated functions will work, but error checking,
     documentation, and tests will be minimal.
-  - [ ] **Potential challenges:** I’ll need to strike a balance here
+  - [x] **Potential challenges:** I’ll need to strike a balance here
     between getting a basic working system and producing something that
     can be easily expanded later.
     - **Update:** Also, this likely could go unsaid, but, if the API

inst/templates/paths.R

@@ -14,7 +14,8 @@
 #' @export
 {{api_abbr}}_{{operation_id}} <- function({{{args}}}{{#has_security}}{{#args}},{{/args}}{{{security_signature}}}{{/has_security}}) {
   {{api_abbr}}_call_api(
-    path = {{{path}}}{{#has_security}},
+    path = {{{path}}},
+    method = "{{method}}"{{#has_security}},
     {{security_arg_list}}{{/has_security}}{{#params_query}},
     query = list({{params_query}}){{/params_query}}{{#params_header}},
     body = list({{params_header}}){{/params_header}}

tests/testthat/_fixtures/fec-paths-audit.R

@@ -32,6 +32,7 @@
 fec_get_audit_case <- function(audit_case_id, cycle, sub_category_id, sort_nulls_last, sort_hide_null, min_election_cycle, audit_id, q, per_page, max_election_cycle, candidate_id, committee_type, qq, page, committee_id, committee_designation, primary_category_id, sort_null_only, sort, api_key = Sys.getenv("FEC_API_KEY")) {
   fec_call_api(
     path = "/audit-case/",
+    method = "get",
     api_key = api_key,
     query = list(audit_case_id = audit_case_id, cycle = cycle, sub_category_id = sub_category_id, sort_nulls_last = sort_nulls_last, sort_hide_null = sort_hide_null, min_election_cycle = min_election_cycle, audit_id = audit_id, q = q, per_page = per_page, max_election_cycle = max_election_cycle, candidate_id = candidate_id, committee_type = committee_type, qq = qq, page = page, committee_id = committee_id, committee_designation = committee_designation, primary_category_id = primary_category_id, sort_null_only = sort_null_only, sort = sort)
   )
@@ -55,6 +56,7 @@ fec_get_audit_case <- function(audit_case_id, cycle, sub_category_id, sort_nulls
 fec_get_audit_category <- function(sort_nulls_last, page, primary_category_name, sort_hide_null, primary_category_id, sort_null_only, per_page, sort, api_key = Sys.getenv("FEC_API_KEY")) {
   fec_call_api(
     path = "/audit-category/",
+    method = "get",
     api_key = api_key,
     query = list(sort_nulls_last = sort_nulls_last, page = page, primary_category_name = primary_category_name, sort_hide_null = sort_hide_null, primary_category_id = primary_category_id, sort_null_only = sort_null_only, per_page = per_page, sort = sort)
   )
@@ -78,6 +80,7 @@ fec_get_audit_category <- function(sort_nulls_last, page, primary_category_name,
 fec_get_audit_primary_category <- function(sort_nulls_last, page, primary_category_name, sort_hide_null, primary_category_id, sort_null_only, per_page, sort, api_key = Sys.getenv("FEC_API_KEY")) {
   fec_call_api(
     path = "/audit-primary-category/",
+    method = "get",
     api_key = api_key,
     query = list(sort_nulls_last = sort_nulls_last, page = page, primary_category_name = primary_category_name, sort_hide_null = sort_hide_null, primary_category_id = primary_category_id, sort_null_only = sort_null_only, per_page = per_page, sort = sort)
   )
@@ -94,6 +97,7 @@ fec_get_audit_primary_category <- function(sort_nulls_last, page, primary_catego
 fec_get_names_audit_candidates <- function(q, api_key = Sys.getenv("FEC_API_KEY")) {
   fec_call_api(
     path = "/names/audit_candidates/",
+    method = "get",
     api_key = api_key,
     query = list(q = q)
   )
@@ -110,6 +114,7 @@ fec_get_names_audit_candidates <- function(q, api_key = Sys.getenv("FEC_API_KEY"
 fec_get_names_audit_committees <- function(q, api_key = Sys.getenv("FEC_API_KEY")) {
   fec_call_api(
     path = "/names/audit_committees/",
+    method = "get",
     api_key = api_key,
     query = list(q = q)
   )

tests/testthat/_fixtures/guru-paths-apis.R

@@ -11,7 +11,8 @@
 #' @export
 guru_list_apis <- function() {
   guru_call_api(
-    path = "/list.json"
+    path = "/list.json",
+    method = "get"
   )
 }
 
@@ -23,7 +24,8 @@ guru_list_apis <- function() {
 #' @export
 guru_get_metrics <- function() {
   guru_call_api(
-    path = "/metrics.json"
+    path = "/metrics.json",
+    method = "get"
   )
 }
 
@@ -35,7 +37,8 @@ guru_get_metrics <- function() {
 #' @export
 guru_get_providers <- function() {
   guru_call_api(
-    path = "/providers.json"
+    path = "/providers.json",
+    method = "get"
   )
 }
 
@@ -49,7 +52,8 @@ guru_get_providers <- function() {
 #' @export
 guru_get_api <- function(provider, api) {
   guru_call_api(
-    path = c("/specs/{provider}/{api}.json", provider = provider, api = api)
+    path = c("/specs/{provider}/{api}.json", provider = provider, api = api),
+    method = "get"
   )
 }
 
@@ -64,7 +68,8 @@ guru_get_api <- function(provider, api) {
 #' @export
 guru_get_service_api <- function(provider, service, api) {
   guru_call_api(
-    path = c("/specs/{provider}/{service}/{api}.json", provider = provider, service = service, api = api)
+    path = c("/specs/{provider}/{service}/{api}.json", provider = provider, service = service, api = api),
+    method = "get"
   )
 }
 
@@ -77,7 +82,8 @@ guru_get_service_api <- function(provider, service, api) {
 #' @export
 guru_get_provider <- function(provider) {
   guru_call_api(
-    path = c("/{provider}.json", provider = provider)
+    path = c("/{provider}.json", provider = provider),
+    method = "get"
   )
 }
 
@@ -90,6 +96,7 @@ guru_get_provider <- function(provider) {
 #' @export
 guru_get_services <- function(provider) {
   guru_call_api(
-    path = c("/{provider}/services.json", provider = provider)
+    path = c("/{provider}/services.json", provider = provider),
+    method = "get"
   )
 }

tests/testthat/_fixtures/trello-paths-board.R

@@ -15,6 +15,7 @@ trello_add_boards <- function(
     token = Sys.getenv("TRELLO_TOKEN")) {
   trello_call_api(
     path = "/boards",
+    method = "post",
     key = key, token = token
   )
 }