New Data.post for sending a payload to a Web API

CHANGELOG.md

@@ -569,6 +569,7 @@
   `Column.map` and `Column.zip`.][7637]
 - [Added `delete_rows` method to Database Table, changed the
   `update_database_table` API into `update_rows`.][7709]
+- [Added `Data.post` method to write to HTTP endpoints.][7700]
 
 [debug-shortcuts]:
   https://github.com/enso-org/enso/blob/develop/app/gui/docs/product/shortcuts.md#debug
@@ -806,6 +807,7 @@
 [7704]: https://github.com/enso-org/enso/pull/7704
 [7615]: https://github.com/enso-org/enso/pull/7615
 [7637]: https://github.com/enso-org/enso/pull/7637
+[7700]: https://github.com/enso-org/enso/pull/7700
 [7709]: https://github.com/enso-org/enso/pull/7709
 
 #### Enso Compiler

distribution/lib/Standard/Base/0.0.0-dev/src/Data.enso

@@ -17,6 +17,7 @@ import project.Network.URI.URI
 import project.Nothing.Nothing
 import project.System.File.File
 from project.Data.Boolean import Boolean, False, True
+from project.Network.HTTP.Request_Body import all
 from project.System.File_Format import Auto_Detect, File_Format
 
 ## ALIAS load, open
@@ -150,24 +151,126 @@ list_directory directory name_filter=Nothing recursive=False =
 
    Arguments:
    - uri: The URI to fetch.
-   - method: The HTTP method to use. Defaults to `GET`.
+   - method: The HTTP method to use. Must be one of `HTTP_Method.Get`,
+     `HTTP_Method.Head`, `HTTP_Method.Delete`, `HTTP_Method.Options`.
+     Defaults to `HTTP_Method.Get`.
+
    - headers: The headers to send with the request. Defaults to an empty vector.
    - try_auto_parse:  If successful should the body be attempted to be parsed to
      an Enso native object.
+
+   > Example
+     Read from an HTTP endpoint.
+
+         import Standard.Base.Data
+         response = Data.fetch URL
+
+   > Example
+     Read from an HTTP endpoint and write the results to a file.
+
+         import Standard.Base.Data
+         file = enso_project.data / "spreadsheet.xls"
+         Data.fetch URL . to_file file
 fetch : (URI | Text) -> HTTP_Method -> Vector (Header | Pair Text Text) -> Boolean -> Any
-fetch uri method=HTTP_Method.Get headers=[] try_auto_parse=True =
-    parsed_headers = headers . map h-> case h of
-        _ : Vector -> Header.new (h.at 0) (h.at 1)
-        _ : Pair -> Header.new (h.at 0) (h.at 1)
-        _ : Header -> h
-        _ -> Error.throw (Illegal_Argument.Error "Invalid header type - all values must be Vector, Pair or Header (got "+(Meta.get_simple_type_name h)+").")
-
-    request = Request.new method uri parsed_headers
-    response = HTTP.new.request request
-
-    if response.code.is_success.not then Error.throw (Request_Error.Error "Status Code" ("Request failed with status code: " + response.code.to_text + ". " + response.body.decode_as_text)) else
-        if try_auto_parse.not then response else
-            response.decode if_unsupported=response . catch handler=(_->response)
+fetch (uri:(URI | Text)) (method:HTTP_Method=HTTP_Method.Get) (headers:(Vector (Header | Pair Text Text))=[]) (try_auto_parse_response:Boolean=True) =
+    HTTP.fetch uri method headers try_auto_parse_response
+
+## ALIAS upload, http post
+   GROUP Input
+   Writes the provided data to the provided URI. Returns the response,
+   parsing the body if the content-type is recognised. Returns an  error if the
+   status code does not represent a successful response.
+
+   Arguments:
+   - uri: The URI to fetch.
+   - body: The data to write. See `Supported Body Types` below.
+   - method: The HTTP method to use. Must be one of `HTTP_Method.Post`,
+     `HTTP_Method.Put`, `HTTP_Method.Patch`. Defaults to `HTTP_Method.Post`.
+   - headers: The headers to send with the request. Defaults to an empty vector.
+   - try_auto_parse:  If successful should the body be attempted to be parsed to
+     an Enso native object.
+
+   ! Specifying Content Types
+
+     If the `body` parameter specifies an explicit content type, then it is an
+     error to also specify additional `Content-Type` headers in the `headers`
+     parameter. (It is not an error to specify multiple `Content-Type` values in
+     `headers`, however.)
+
+   ! Supported Body Types
+
+     - Request_Body.Text: Sends a text string, with optional encoding and content
+       type.
+     - Request_Body.Json: Sends an Enso object, after converting it to JSON.
+     - Request_Body.Binary: Sends a file.
+     - Request_Body.Form_Data: Sends a form encoded as key/value pairs. The keys
+       must be `Text`, and the values must be `Text` or `File`.
+     - Request_Body.Empty: Sends an empty body.
+
+     Additionally, the following types are allowed as the `body` parameter:
+
+     - Text: shorthand for `Request_Body.Text that_text`.
+     - File: shorthand for `Request_Body.Binary that_file`.
+     - Any other Enso object: shorthand for `Request_Body.Json that_object`.
+
+   > Example
+     Write a text string to an HTTP endpoint.
+
+         import Standard.Base.Data
+         response = Data.post url_post (Request_Body.Text "hello world")
+
+   > Example
+     Write JSON to an HTTP endpoint.
+
+         import Standard.Base.Data
+         json = Json.parse '{"a": "asdf", "b": 123}'
+         response = Data.post url_post json
+
+   > Example
+     Write an Enso object to an HTTP endpoint.
+
+         import Standard.Base.Data
+         response = Data.post url_post (My_Type.Value 12)
+
+   > Example
+     Write a text string to an HTTP endpoint, with a specific text encoding.
+
+         import Standard.Base.Data
+         body = Request_Body.Text 'Hello World!' encoding=Encoding.utf_16_le
+         response = Data.post url_post body
+
+   > Example
+     Write a text string to an HTTP endpoint, with a specific content type.
+
+         import Standard.Base.Data
+         body = Request_Body.Text 'a,b,c\n' content_type="text/csv"
+         response = Data.post url_post body
+
+   > Example
+     Write the contents of a file to an HTTP endpoint.
+
+         import Standard.Base.Data
+         test_file = enso_project.data / "sample.png"
+         response = Data.post url_post (Request_Body.Binary test_file)
+
+   > Example
+     Write a multipart form to an HTTP endpoint.
+
+         import Standard.Base.Data
+         test_file = enso_project.data / "sample.png"
+         form_data = Map.from_vector [["key", "val"], ["a_file", test_file]]
+         response = Data.post url_post (Request_Body.Form_Data form_data)
+
+   > Example
+     Write a URL-encoded form to an HTTP endpoint.
+
+         import Standard.Base.Data
+         test_file = enso_project.data / "sample.txt"
+         form_data = Map.from_vector [["key", "val"], ["a_file", test_file]]
+         response = Data.post url_post (Request_Body.Form_Data form_data url_encoded=True)
+post : (URI | Text) -> Request_Body -> HTTP_Method -> Vector (Header | Pair Text Text) -> Boolean -> Any
+post (uri:(URI | Text)) (body:Request_Body=Request_Body.Empty) (method:HTTP_Method=HTTP_Method.Post) (headers:(Vector (Header | Pair Text Text))=[]) (try_auto_parse_response:Boolean=True) =
+    HTTP.post uri body method headers try_auto_parse_response
 
 ## ALIAS download, http get
    GROUP Input