StediDOCS
This product is in Public Preview

Converter

Converter is a collection of serverless APIs that provide a simple and convenient way of converting files into different formats.

We currently support the following formats:

  • JSON to CSV
  • CSV to JSON
  • XML to JSON

Note: JSON to XML is currently not supported.

SDK and examples

The Converter TypeScript SDK is available to install with NPM:

npm i @stedi/sdk-converter-node

We provide an example TypeScript project with the latest SDK client to get you started: converter-examples

Using Converter APIs

Prerequisites

Make sure you have set up an API key and that you include the key in the Authorization header when you make a request.

CSV to JSON

curl --location --request POST 'https://converter.stedi.com/2021-10-01/convert_csv_to_json' \
--header "Authorization: Key $STEDI_API_KEY" \
--header "Content-Type: application/json" \
--data-raw '{
 "input_csv": "heading1,heading2,heading3\r\nrow1col1,row1col2,row1col3\r\nrow2col1,row2col2,row2col3"
}'

The API will return the following JSON object:

{
  "output_json": [
    {
      "heading1": "row1col1",
      "heading2": "row1col2",
      "heading3": "row1col3"
    },
    {
      "heading1": "row2col1",
      "heading2": "row2col2",
      "heading3": "row2col3"
    }
  ]
}

JSON to CSV

curl --location --request POST 'https://converter.stedi.com/2021-10-01/convert_json_to_csv' \
--header "Authorization: Key $STEDI_API_KEY" \
--header "Content-Type: application/json" \
--data-raw '{
 "input_json": [
  {
   "heading1": "row1col1",
   "heading2": "row1col2",
   "heading3": "row1col3"
  },
  {
   "heading1": "row2col1",
   "heading2": "row2col2",
   "heading3": "row2col3"
  }
 ]
}'

The API will return the following JSON response:

{
  "output_csv": "heading1,heading2,heading3\r\nrow1col1,row1col2,row1col3\r\nrow2col1,row2col2,row2col3"
}

XML to JSON

curl --location --request POST 'https://converter.stedi.com/2021-10-01/convert_xml_to_json' \
--header "Authorization: Key $STEDI_API_KEY" \
--header "Content-Type: application/json" \
--data-raw '{
 "input_xml": "<order_purchase><item><name>item1</name><quantity>5</quantity></item><item><name>item2</name><quantity>9</quantity></item></order_purchase>"
}'

The API will return the following JSON response:

{
  "output_json": {
    "order_purchase": {
      "item": [
        {
          "name": "item1",
          "quantity": 5
        },
        {
          "name": "item2",
          "quantity": 9
        }
      ]
    }
  }
}

Using curl with binary parameter files

The above examples use curls --data-raw parameter to send data to the API. It's often easier to use --data-binary to pass a file which contains the API arguments instead. In order to do this, follow these steps:

  • String-encode the arguments into a file using jq
INPUT_FILE=`cat my_csv_file.csv | jq -Rs .`
printf '{"input_csv": %s, "options": {"use_header": true}}' $INPUT_FILE > /tmp/arguments_file
  • Pass the arguments file to curl
curl --location --request POST 'https://converter.stedi.com/2021-10-01/convert_csv_to_json' \
--header "Authorization: Key $STEDI_API_KEY" \
--header "Content-Type: application/json" \
--data-binary '@/tmp/arguments_file'

Compression

The APIs support request/response payload compression in order to allow uncompressed payloads that are larger than 6MB.

To receive a compressed payload set the Accept-Encoding: gzip header in your request:

curl --location --request POST 'https://converter.stedi.com/2021-10-01/convert_xml_to_json' \
--header "Authorization: Key $STEDI_API_KEY" \
--header "Accept-Encoding: gzip" \
--header "Content-Type: application/json" \
--data-raw '{
 "input_xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><order_purchase><item><name>item1</name><quantity>5</quantity></item><item><name>item2</name><quantity>9</quantity></item></order_purchase>"
}'

In order to send gzip compressed payload request you will have to compress the whole body of the request payload and set the Content-Type: application/gzip header:

INPUT_FILE=`cat my_csv_file.csv | jq -Rs .`
printf '{ "input_csv": %s}' $INPUT_FILE | gzip -c > /tmp/compressed_payload.tgz
curl --location --request POST 'https://converter.stedi.com/2021-10-01/convert_csv_to_json' \
--header "Content-Type: application/gzip" \
--header "Authorization: Key $STEDI_API_KEY" \
--data-binary '@/tmp/compressed_payload.tgz'

Non UTF-8 files

Some documents, such as certain XML documents are encoded in formats other than UTF-8, and will need to be converted before being sent to the API using curl. The built-in iconv utility can be used for this purpose.

Here's an example of converting a UTF-16 encoded XML file to JSON.

INPUT_FILE=`cat my_utf16_xml_file.xml | iconv -f UTF-16 -t UTF-8 | jq -Rs .`
printf '{"input_xml": %s}' $INPUT_FILE > /tmp/input_file
curl --location --request POST 'https://converter.stedi.com/2021-10-01/convert_xml_to_json' \
--header "Content-Type: application/json" \
--header "Authorization: Key $STEDI_API_KEY" \
--data-binary '@/tmp/input_file'

API Reference