Array Serialization Formats

APIs implement various array serialization schemes based on their specific use cases. To ensure broad compatibility, APIMatic supports six array serialization methods for query and form parameters: Indexed, UnIndexed, Plain, CSV, PSV, and TSV.

Configure Array Serialization

To leverage this feature, use the ArraySerialization CodeGen setting to define your preferred array serialization format. The default format is Indexed:

"info": {
    ...,
    "x-codegen-settings": {
        "ArraySerialization": "Indexed"
    }
}

Serialization Formats and Examples

The following formats are supported for form and query parameters:

Indexed

Indexed array serialization includes an explicit index for each value.

businessAsset[0]=1&businessAsset[1]=2

UnIndexed

UnIndexed format appends new values to an array without specifying their positions.

businessAsset[]=1&businessAsset[]=2

Plain

Plain format represents values as repeated variable assignments.

businessAsset=1&businessAsset=2

CSV

CSV format separates array elements with commas and is applicable only to query parameters.

businessAsset=1,2

PSV

PSV format separates array elements with pipes and is applicable only to query parameters.

businessAsset=1|2

TSV

TSV format separates array elements with tabs and is applicable only to query parameters.

businessAsset=1\t2

Usage in SDK

Array serialization can be utilized during request construction or deserialization within SDKs generated using APIMatic. Here’s a usage example:

TypeScript

const businessAsset: number[] = [
  1,
  2
];

async function makeApiCall() {
  try {
    const { result, ...httpResponse } = await controller.getArraySerializedInQuery(businessAsset);
  } catch (error) {
    if (error instanceof ApiError) {
      const errors = error.result;
    }
  }
};
makeApiCall();

Java

List<Integer> businessAsset = Arrays.asList(
    1,
    2
);

controller.getArraySerializedInQueryAsync(businessAsset).thenAccept(result -> {
    System.out.println(result);
}).exceptionally(exception -> {
    exception.printStackTrace();
    return null;
});

Python

businessAsset = [
    1,
    2
]

try:
    result = controller.get_array_serialized_in_query(businessAsset)
    print(result)
except APIException as e:
    print(e)

PHP

$businessAsset = [
    1,
    2
];

try {
    $result = $client->getController()->getArraySerializedInQuery($businessAsset);
    var_dump($result);
} catch (ApiException $e) {
    echo 'Caught ApiException: ',  $e->getMessage(), "\n";
}

.NET

List<int> businessAsset = ApiHelper.JsonDeserialize<List<int>>("[1,2]");

Standard.Models.ServerResponse result = null;
try
{
    result = await this.controller.GetArraySerializedInQueryAsync(businessAsset);
}
catch (ApiException)
{
}

Ruby

businessAsset = [
  1,
  2
]

begin
  result = client.controller.get_array_serialized_in_query(businessAsset)
  puts result
rescue APIException => e
  puts "Caught APIException: #{e.message}"
end

Go

businessAsset := []int{
    1,
    2,
}

apiResponse, err := controller.GetArraySerializedInQuery(ctx, businessAsset)
if err != nil {
    log.Fatalln(err)
} else {
    fmt.Println(apiResponse.Data)
    fmt.Println(apiResponse.Response.StatusCode)
}