Create a list

Creates a new list definition.

When you create a new list, you define the properties of a new tabular data set, but the list initially has no contents. List contents are loaded and managed by using other endpoints that are available with the List Data API.

A list's properties describe the structure, functionality, and state of a list. A list's contents, which are the list's data, is a sub-resource of the list.

The structure of a list represents the data that you will import as the list contents. The list data description is represented by column information objects. The column objects map information about the source data (for example, column name, data type, and position) to the list's structure.

When you create the list's structure, you need to identify at least one column as a key. This column is used to construct a lookup key for the record, which is used to retrieve the record from the contents data store. You can create complex lookup keys by identifying more than one column as a key.

You must add lists to a folder. A list inherits the permissions of the folder of which it is a member. The default folder '/SAS Content/Products/List Data' provides public permissions. You can move lists to different folders and manage authorizations for a folder by using SAS Environment Manager.

A list can be immutable, which means a client has only a single opportunity to load contents. Once an immutable list has contents, you cannot update the list. You can only delete it.

The state of a list can be either deployed or developing. You cannot delete a deployed list.

A list can have an expiry that is associated only with the list's rows. This expiry value is a UNIX timestamp, which enables consumers of list data to choose whether to ignore expired list items. No action is taken by the service once the expiry is reached.

The 'defaultExpiry' property is the time, in seconds, after which newly added rows are considered expired. When rows are added, an expiry property is also added, which is equal to the current UNIX Epoch time plus the default expiry value. Enforcement of the expiry is left to the consumer, and no action is taken by the service when the expiration time is reached.

You can define a list that supports storing multiple records by using the same key value. This means that when a client retrieves a value by using a lookup key, more than one record could be returned. You need to identify this type of list when you create a new list. Once created, you cannot convert this list type to a standard list type.

Creating a list also creates the first revision of that list, which you can see by using the GET /lists/{listId}/revisions endpoint.