update readme with clarifying socrata api documentation

DESCRIPTION

@@ -10,8 +10,8 @@ Description: Provides easier interaction with
     format and manages throttling by 'Socrata'.
     Users can upload data to 'Socrata' portals directly
     from R.
-Version: 1.8.0-10
-Date: 2019-01-27
+Version: 1.8.0-11
+Date: 2019-09-10
 Author: Hugh Devlin, Ph. D., Tom Schenk, Jr., Gene Leynes, Nick Lucius, John Malc, Mark Silverberg, and Peter Schmeideskamp
 Maintainer: "Tom Schenk Jr." <[email protected]>
 Depends:
@@ -29,4 +29,4 @@ Suggests:
 License: MIT + file LICENSE
 URL: https://github.com/Chicago/RSocrata
 BugReports: https://github.com/Chicago/RSocrata/issues
-RoxygenNote: 6.1.0
+RoxygenNote: 6.1.1

R/RSocrata.R

@@ -472,7 +472,14 @@ checkUpdateResponse <- function(json_data_to_upload, url, http_verb, email, pass
 
 #' Write to a Socrata dataset (full replace or upsert)
 #'
-#' @description Method for updating Socrata datasets 
+#' @description Method for updating Socrata datasets with the Socrata Open Data API (SODA). 
+#' 
+#' Note: SODA differs in functionality from the Socrata Data Management API.
+#' The Data Management API stages and transforms data in drafts on Socrata during the data ingress cycle. With any data updates to Socrata datasets that utilize
+#' one or more on-platform data transformations, use the Data Management API to continue to apply those transformations to any new data.
+#' 
+#' If you do not need or use the on-platform transform functionality for a given dataset, the SODA API and \code{write.socrata()}
+#' will continue to perform as expected. For more on the Socrata Data Management API, see the latter API's documentation \url{https://socratapublishing.docs.apiary.io/#}  
 #'
 #' @param dataframe - dataframe to upload to Socrata
 #' @param dataset_json_endpoint - Socrata Open Data Application Program Interface (SODA) endpoint (JSON only for now)

README.md

@@ -101,6 +101,9 @@ allSitesDataFrame$title # Names of each dataset
 ```
 
 ### Upload data to portal
+
+Note: ```write.socrata()``` writes directly to Socrata datasets using the Socrata Open Data API, which differs in functionality from the [Socrata Data Management API](https://socratapublishing.docs.apiary.io/#). Creating datasets with the Socrata user interface, or directly with the Data Management API, uses drafts to stage and transform data during the data ingress cycle. With any data updates to Socrata datasets that utilize one or more on-platform data transformations (like adding a georeference), use the Data Management API to continue to apply those transformations to any new data. If your dataset schema is exactly the same between your source and the Socrata dataset, and you do not need the on-platform transform functionality, the SODA API and ```write.socrata()``` will continue to perform as expected. For more on the difference between the SODA API and the Socrata Data Management API, see the latter API's documentation [here](https://socratapublishing.docs.apiary.io/#).
+
 ```r
 # Store user email and password
 socrataEmail <- Sys.getenv("SOCRATA_EMAIL", "[email protected]")