Using ListWrap<T>

ListWrap<T> is a .NET wrapper class around .NET List<T>. It takes the structure:

{
  Count: long,
  Data: List<T>
}

In JSON terms, a List<T> may be represented as a simple array.

Most Identity Panel APIs that return a ListWrap use the the Count property to list the total number of results e.g. for a paged query (with most APIs having a default page size of 10). Any API that return or require a list-like result will return or accept either a ListWrap or a sub-type of ListWrap to avoid having a JSON array as a root level object.

JSON Serialization

In application/json ListWrap has fairly simple behavior. The primary caveat is that all items in the data array must have a type annotation (unless a simple value type, e.g. string or long). For example, a list of history entries would have:

{
  Count: 1,
  Data: [
    {
      "$type": "SoftwareIDM.PanelModel.Models.HistoryRecord, SoftwareIDM.PanelModel",
      "Id": ...
      ...
    }
  ]
}

NOTE: TypeNames and sample JSON payloads for objects may be obtained using the RuleTester to query for objects. Full Type names of a queried object may be derived with the rule:

TypeName(context, true)

By using $type specification, ListWrap will allow polymorphic sub-typing of whatever type is specified by the API endpoint. For example, ListWrap<HistoryRecord> will allow HistoryRecord but also any of it's 13+ sub-types.

BSON Serialization

For Bson serialization ListWrap implements ICustomSerializer to produce binary array data. This is important as it allows serialization of result sets larger than 16MB, as may happen e.g. when refreshing hashes for a large object silo.

The binary structure is:

Count: 8 bytes
Data: [
  <binary data>
]

The binary data format depends on the objects being serialized in the data stream (as specified by the Generic Type constraint of the LIstWrap):

• byte[]:
  length: 4 bytes
  raw binary data
• Guid:
  byte array, 16 bytes
• String:
  length: 4 bytes
  UTF8 binary data
• T : ICustomSerializer:
  serialized via the WriteToStream() method
• T:
  length: 4 bytes
  binary data of standard BSON serialization

NOTES:

De-serialization uses essentially the same rules, with the observation that ICustomSerializer objects self-unpack directly using the binary stream, and BSON is constrained to de-serialize conforming with the ListWrap generic type constraint.

Because Identity Panel data representation classes make heavy use of element name shortening to reduce BSON payload sizes (about 1/3 reduction in serialized data size prior to compression), you should only use BSON as a data serialization mechanism if using Identity Panel .NET dlls. Otherwise producing valid payloads will be very challenging.