stop_for_status function.

Turns http errors into R errors

NAMESPACE

@@ -15,6 +15,7 @@ export(POST)
 export(PUT)
 export(set_config)
 export(set_cookies)
+export(stop_for_status)
 export(text_content)
 export(timeout)
 export(use_proxy)

R/content.r

@@ -17,6 +17,7 @@
 #'
 #' @param ... additional parameters passed to conversion function
 #' @param x request object
+#' @family response methods
 #' @export
 content <- function(x) {
   stopifnot(is.response(x))

R/response.r

@@ -16,6 +16,7 @@
 #'   \item \code{config} configuration for the request
 #' }
 #' @name response
+#' @family response methods
 NULL
 
 response <- function(...) {  
@@ -49,3 +50,30 @@ as.character.response <- function(x, ...) {
   text_content(x)
 }
 
+#' Throw error on http error.
+#'
+#' Converts http errors to R errors - this is useful if you want to ensure
+#' the appropriate action is taken when an http request fails.
+#'
+#' @param x a request object
+#' @export
+#' @family response methods
+#' @examples
+#' x <- GET("http://httpbin.org/status/320")
+#' stop_for_status(x) # nothing happens
+#' x <- GET("http://httpbin.org/status/404")
+#' stop_for_status(x)
+stop_for_status <- function(x) {
+  stopifnot(is.response(x))
+
+  status <- x$status_code
+  if (status < 400) return(invisible())
+
+  if (status >= 400 & status < 500) {
+    stop("http client error (", status, ")", call. = FALSE)
+  }
+  if (status >= 500 & status < 600) {
+    stop("http server error (", status, ")", call. = FALSE)
+  }
+}
+

README.md

@@ -12,11 +12,13 @@ Key features:
   across requests.
 
 * a request object which captures the body of the request along with
-  http status code, cookies, headers, timings and other useful information
+  http status code, cookies, headers, timings and other useful information.
 
-* an easy way to access the content of the response as a raw vector
-  (`content`), character vector (`text_content`), or parsed into an R object
-  (`parsed_content`, currently for html, xml, json, png and jpeg)
+  * response content is available as a raw vector (`content`), a character
+    vector (`text_content`), or parsed into an R object (`parsed_content`,
+    currently for html, xml, json, png and jpeg)
+
+  * convert http errors into R errors with `stop_for_status`
 
 * wrapper functions for the most common configuration options:
   `set_cookies`, `add_headers`, `authenticate`, `use_proxy`, `verbose`,

inst/tests/test-config.r

@@ -1,7 +1,7 @@
 context("Config")
 
 test_that("timeout enforced", {
-  expect_error(GET("http://httpbin.org/delay/1", timeout(0.5)), "timed out")
+  expect_error(GET("http://httpbin.org/delay/1", timeout(0.5)), "time-out")
 })
 
 test_that("basic authentication works", {

inst/tests/test-request.r

@@ -8,6 +8,17 @@ test_that("status codes returned as expected", {
 
 })
 
+test_that("status converted to errors", {
+
+  s320 <- GET("http://httpbin.org/status/320")
+  s404 <- GET("http://httpbin.org/status/404")
+  s500 <- GET("http://httpbin.org/status/500")
+
+  expect_equal(stop_for_status(s320), NULL)
+  expect_error(stop_for_status(s404), c("404", "client"))
+  expect_error(stop_for_status(s500), c("500", "server"))  
+})
+
 test_that("headers returned as expected", {
   round_trip <- function(...) {
     req <- GET("http://httpbin.org/headers", add_headers(...))

man/content.Rd

@@ -31,4 +31,8 @@
   \item \code{image/jpeg}: \code{\link[jpeg]{readJPEG}}
   \item \code{image/png}: \code{\link[jpeg]{readPNG}} }
 }
+\seealso{
+  Other response methods: \code{\link{response}},
+  \code{\link{stop_for_status}}
+}
 

man/response.Rd

@@ -18,4 +18,9 @@
   \code{time} request timing information \item
   \code{config} configuration for the request }
 }
+\seealso{
+  Other response methods: \code{\link{content}},
+  \code{\link{parsed_content}},
+  \code{\link{stop_for_status}}, \code{\link{text_content}}
+}
 

man/stop_for_status.Rd

@@ -0,0 +1,26 @@
+\name{stop_for_status}
+\alias{stop_for_status}
+\title{Throw error on http error.}
+\usage{
+  stop_for_status(x)
+}
+\arguments{
+  \item{x}{a request object}
+}
+\description{
+  Converts http errors to R errors - this is useful if you
+  want to ensure the appropriate action is taken when an
+  http request fails.
+}
+\examples{
+x <- GET("http://httpbin.org/status/320")
+stop_for_status(x) # nothing happens
+x <- GET("http://httpbin.org/status/404")
+stop_for_status(x)
+}
+\seealso{
+  Other response methods: \code{\link{content}},
+  \code{\link{parsed_content}}, \code{\link{response}},
+  \code{\link{text_content}}
+}
+