Skip to content

description: >- RESTful APIs use various encodings like JSON, XML, URL encoding and Base64 for efficient data transmission and compatibility.

Body / Encoding

Common Encoding Types in RESTful APIs

RESTful APIs have different types of bodies. These are called 'encoding types', to format data. Within Alumio, JSON is generally preferred. Not all APIs support JSON, however. There are also reasons why JSON is not always preferable. Files are, for example, often encoded in Base64 to facilitate transmission without running into encoding errors.

Here are some common encoding types:

JSON (JavaScript Object Notation):

  • Description: Widely used for data serialization.
  • Content-Type: application/json
  • Format: 
{
  "key": "value",
  "array": [1, 2, 3],
  "nested": {
    "subkey": "subvalue"
  }
}

XML (eXtensible Markup Language):

  • Description: Hierarchical and versatile markup language. XML is fairly old, but still often used. Generally by older systems. XML is pretty inefficient when it comes to data ("key": "value" compared to <key>value</key> , and in arrays you don't even need the key for JSON). And somewhat less human-readable than JSON is.
  • Content-Type: application/xml or text/xml
  • Format: 
<root>
  <element key="value"/>
  <array>
    <item>1</item>
    <item>2</item>
    <item>3</item>
  </array>
  <nested>
    <subkey>subvalue</subkey>
  </nested>
</root>

Notes on XML to JSON conversion and vice-versa

Alumio will convert XML to JSON when it gets it. XML is still used often, so it's important to know about it's peculiarities.

Attributes

XML has 'attributes': <element key="value"/> , JSON does not. So, if the converter gets in:

<item sku="ABC">
  <price>5.25</price>
</item>

It will convert it into this for JSON:

{
  "item": {
    "@sku": "ABC",
    "price": 5.25
  }
}

Arrays

In JSON, an array is clearly marked ( [] ). In an XML, an array is inferred. Let's say you have a list:

<fruits>
  <fruit>apple</fruit>
  <fruit>pear</fruit>
  <fruit>mango</fruit>
</fruits>

This is clearly an array, but XML doesn't directly come out and says this. Only because there are multiple <fruit> nodes, can it be inferred. Above example would become this in JSON:

{
  "fruits": {
    "fruit": [
      "apple",
      "pear",
      "mango"
    ]
  }
}

Note that precisely BECAUSE XML doesn't have the 'array' type, it uses the <fruits><fruit> pattern.

However, what happens when an XML contains a node that should be a list, but only contains a single item?

<fruits>
  <fruit>apple</fruit>
</fruits>

The XML -> JSON converter doesn't 'know' it should be a list, and therefore will turn it into this:

{
  "fruits": {
    "fruit": "apple"
  }
}

If you create transformers that expect fruits.fruit to be a list, you're gonna be in trouble. So be sure to always change these to arrays before modifying them.

Types

XML doesn't recognize data-types. JSON does. When enabled, the XML -> JSON converter will try to infer what the type is. This can be very dangerous - it might for example infer that -034 is a number, which means the JSON value will become 34 . However, you might need the actual string -034. Generally, it's best to disable this behaviour in the Subscriber.

URL Encoding:

  • Description: Used for encoding data in URLs. There are many 'unsafe' characters in URLs (for example, / means something very particular in a URL, so you can't send it like that), so if you want to send data through a URL you need to encode those characters. URL-encoding is the generally accepted way to do this.
  • Content-Type: used for URLs, generally not for the bodies. Therefore, doesn't have its own Content-Type.
  • Example: 
space%20encoded

Form Data (x-www-form-urlencoded):

  • Description: Commonly used in HTML forms. It encodes all input data into key-value pairs. This is a very basic way to send basic information - like a contact form. More complex applications are often found in EDI & PunchOut, where this is used to - for example - send the contents of a shopping cart (ORDERITEM_1_NAME , ORDERITEM1_QUANTITY , etc.).
  • Content-Type: application/x-www-form-urlencoded
  • Example:
key1=value1&key2=value2

Binary Encoding (Base64):

  • Description: Converts binary data to ASCII characters. This is 'non-destructive' and does not compress data. Therefore it's easy to encode and decode a file this way. The use of Base64 is that by encoding a file to ASCII characters (which all systems can understand), files are transmitted in a 'manageable' way, preventing any errors.
  • Example:
SGVsbG8gV29ybGQh

Multipart Form Data:

  • Description: Used for sending binary data or files.
  • Example:
--Boundary123
Content-Disposition: form-data; name="text_field"

This is a text field.
--Boundary123
Content-Disposition: form-data; name="file"; filename="example.txt"
Content-Type: text/plain

Contents of the file go here.
--Boundary123--

In this example:

  • The boundary (in this case, "Boundary123") is used to separate different parts of the form data.
  • Each part starts with Content-Disposition: form-data; name="...", indicating the name of the field.
  • For the file field, additional information like filename and Content-Type is provided.
  • The actual content of each part follows the headers.

Remember, the boundary should be unique and not appear in the content of the parts. The final boundary includes an extra "--" (--Boundary123--) to indicate the end of the multipart content.

This example is a simple illustration, and in real-world scenarios, you might use this encoding when uploading files or sending a combination of text and binary data through an HTML form.