{
  "Protocol": "AIXE",
  "Version": "1.0",
  "Endpoint": "/aixe/owner/lists/create-list/",
  "Method": "POST",
  "ContentType": "application/json",
  "DiscoveryRequest": "GET /aixe/owner/lists/create-list/?",
  "AccessType": "Site Administrator",
  "Purpose": "Create an empty named list ready for generic values and descriptive labels.",
  "ProtocolReference": {
    "ProtocolHome": "http://aixeprotocol.com/",
    "CanonicalUsageContract": "http://aixeprotocol.com/usage/?",
    "Whitepaper": "http://aixeprotocol.com/whitepaper/full-spec.html",
    "Inventor": "Gregory Oglethorpe"
  },
  "RequiredFields": {
    "PersonAuthenticationToken": {
      "Type": "string",
      "Description": "Secret temporary token returned by /aixe/account/login/. Its active account must currently have Administrator or Site Administrator role. Resource keys and browser cookies do not authenticate this API.",
      "Required": true,
      "SubmittedIn": "JSON body"
    },
    "ListName": {
      "Type": "string",
      "Description": "Unique nonblank list name, maximum 200 characters; surrounding whitespace is trimmed. HomePageProductStrip is the exact name consumed by the homepage; renaming it disconnects that strip.",
      "Required": true,
      "SubmittedIn": "JSON body"
    }
  },
  "OptionalFields": {
    "ListDescription": {
      "Type": "string or null",
      "Description": "Purpose or explanation of the list, maximum 2,000 characters. Omit on update to preserve; null or empty clears it.",
      "Required": false,
      "SubmittedIn": "JSON body"
    },
    "SuggestedMinimumItems": {
      "Type": "integer or null",
      "Description": "Optional nonnegative suggested item count, at most 2147483647. Informational only. Omit on update to preserve; null clears. Cannot exceed a supplied or stored maximum.",
      "Required": false,
      "SubmittedIn": "JSON body"
    },
    "SuggestedMaximumItems": {
      "Type": "integer or null",
      "Description": "Optional nonnegative suggested item count, at most 2147483647. Informational only. Omit on update to preserve; null clears. Cannot be below a supplied or stored minimum.",
      "Required": false,
      "SubmittedIn": "JSON body"
    }
  },
  "BusinessRules": [
    "All business actions, including reads, require a current active Administrator or Site Administrator account authenticated by PersonAuthenticationToken. Contract discovery contains no private list data.",
    "Use POST JSON for keys and action inputs. Unknown fields are rejected. Numeric internal IDs are never returned.",
    "Suggested minimum and maximum counts never restrict adding or deleting items. Values remain generic text; descriptions identify them for people.",
    "New items append. Removing an item closes order gaps. Reorder assigns consecutive values starting at 1 in one transaction.",
    "Updates preserve omitted fields. Description and suggested-count fields accept null to clear. Names and values cannot be empty.",
    "Delete-list requires an empty list without remaining relationships. Deleting a list item never deletes the product or other resource named by its value.",
    "HomePageProductStrip supplies the homepage\u0027s first four positions. Only matching active products render. Renaming or deleting this list, or changing its items, affects the homepage.",
    "Actions execute directly with the administrator token and their declared inputs. These actions send no emails."
  ],
  "Workflow": "Log in as an administrator; search lists; select ListGroupKey; read items. For reorder, collect all unfiltered pages before submitting the desired key sequence. Read SuccessCode after every action.",
  "ResponseFields": {
    "SuccessCode": "SUCCESS only when the operation completed; HTTP 200 alone is not success.",
    "Lists": "list-lists: bounded list summaries.",
    "List": "get-list/create-list/update-list: one list with ListGroupKey, CreationDate, ListName, ListDescription, SuggestedMinimumItems, SuggestedMaximumItems and ItemCount.",
    "Items": "list-items: ordered item records with ListGroupItemKey, CreationDate, ItemValue, ItemDescription and OrderBy.",
    "Item": "get-item/add-item/update-item: one item record using the same fields.",
    "Pagination": "list-lists/list-items return TotalMatches, ReturnedCount, HasMore and NextCursor; follow NextCursor while HasMore is true.",
    "Mutations": "delete-list returns Deleted and ListGroupKey. delete-item/reorder-items return ListGroupKey, ItemCount, Deleted and Reordered. add-item also returns ItemCount."
  },
  "ActionResponse": {
    "RequiredResponseFields": [
      "SuccessCode"
    ],
    "SuccessCodes": [
      "SUCCESS"
    ],
    "FailureCodes": [
      "UNAUTHORIZED",
      "VALIDATION_FAILED",
      "NOT_FOUND",
      "CONFLICT",
      "BUSINESS_RULE_FAILED",
      "FAILED"
    ],
    "MissingOrEmptyResponse": "Treat as failure; never assume the action completed."
  },
  "Recovery": {
    "UNAUTHORIZED": "Log in with an active administrator account; do not substitute a resource key for the token.",
    "VALIDATION_FAILED": "Correct the named inputs and submit the action again.",
    "NOT_FOUND": "Refresh the selected list or item keys within authorized scope.",
    "CONFLICT": "Read current data and correct the conflicting name or key.",
    "BUSINESS_RULE_FAILED": "Remove remaining list items or resolve referenced relationships before deleting a list.",
    "FAILED": "The operation could not complete; inspect current resource state before retrying."
  }
}