Skip to main content

Data.post

Data.posturibodymethodheadersresponse_format

Group: Output
Aliases: http post, upload

Documentation​

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.
  • response_format: The format to use for interpreting the response. Defaults to Auto_Detect. If Raw_Response is selected or if the format cannot be determined automatically, a raw HTTP Response will be returned.

Examples​

Write a text string to an HTTP endpoint.​

      import Standard.Base.Data
      response = Data.post url_post (Request_Body.Text "hello world")

Write JSON to an HTTP endpoint.​

      import Standard.Base.Data
      json = Json.parse '{"a": "asdf", "b": 123}'
      response = Data.post url_post json

Write an Enso object to an HTTP endpoint.​

      import Standard.Base.Data
      response = Data.post url_post (My_Type.Value 12)

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

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

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)

Write a multipart form to an HTTP endpoint.​

      import Standard.Base.Data
      test_file = enso_project.data / "sample.png"
      form_data = Dictionary.from_vector [["key", "val"], ["a_file", test_file]]
      response = Data.post url_post (Request_Body.Form_Data form_data)

Write a URL-encoded form to an HTTP endpoint.​

      import Standard.Base.Data
      test_file = enso_project.data / "sample.txt"
      form_data = Dictionary.from_vector [["key", "val"], ["a_file", test_file]]
      response = Data.post url_post (Request_Body.Form_Data form_data url_encoded=True)

Remarks​

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.

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.)

Default Content Types​

The following specifies the default content type for each Request_Body type.

  • Request_Body.Text: text/plain
  • Request_Body.Json: application/json
  • Request_Body.Binary: application/octet-stream
  • Request_Body.Form_Data: If url_encoded is True: application/x-www-form-urlencoded If url_encoded is False: multipart/form-data
  • Request_Body.Empty: No content type is sent
  • Text: text/plain
  • File: application/octet-stream
  • Any other Enso object: application/json

Specifying Text Encodings​

Text encoding can be specified in the encoding parameter to the Request_Body.Text constructor. This value will be added to the Content-Type header.

If a value for encoding is specified, but no value for content_type is specified, then "text/plain" is used as the content type.