Child pages
  • WHM API 1 - Return Data

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

 

Introduction

Excerpt

WHM API 1 outputs data in either JSON or XML format.

 The output format depends on the options that you choose when you call the function.

  • We strongly recommend that you use JavaScript Object Notation (JSON).
  • Extensible Markup Language (XML) requires additional computational resources, and has complex requirements that can cause difficulty during the development process. This API's XML output is not compliant with XML standards, and it may result in validation errors.
    Multiexcerpt include
    MultiExcerptNameLong Warning
    PageWithExcerptLIB:_XMLDeprecated

Basic return data  

Both JSON and XML output return data as hashes or arrays of hashes. All WHM API 1 function output follows the following basic structure:

  • A top-level hash contains the data and metadata hashes. In XML output, <result> tags wrap the top-level hash of output.
    • The data hash contains the function's output parameters.
    • The  metadata hash contains the function's metadata parameters.

Metadata

Warning
titleImportant:
  • WHM API 1 function documentation does not include metadata parameters in the table of return parameter information. 
  • WHM API 1 calls via the command line do not return the metadata that other methods return if they experience errors that prevent a successful function run. To check for errors in code that calls WHM API 1 functions via the command line, validate the command line return for a nonzero exit code instead.

The metadata hash includes the following output parameters:

Metadata parameterTypeDescriptionPossible valuesExample
versionintegerThe WHM API version.For WHM API 1 functions, this value is always 1.1
reasonstringA message of success, or a reason for failure.
  • OK
  • An error message.
OK
resultBooleanWhether the function succeeded.
  • 1 — Success.
  • 0 — Failure.
1
commandstringThe WHM API 1 function name.Any WHM API 1 function's name.listaccts
Note
titleNote:

If the function returns a hash with a single key whose value is an array, the metadata will include the payload_is_literal output parameter with a value of 1. You will only receive this parameter when you call WHM API's rename_mysql_database or rename_mysql_user functions, or when you call certain UAPI functions via WHM API.

Example

The accountsummary function's output is typical of WHM API 1 output:

Localtab Group
Localtab
activetrue
titleJSON
Code Block
languagetext
linenumberstrue
{
  "data": {
    "acct": [
      {
        "maxaddons": "unlimited",
        "ip": "10.215.214.95",
        "min_defer_fail_to_trigger_protection": "5",
        "legacy_backup": 0,
        "diskused": "14M",
        "maxftp": "unlimited",
        "startdate": "13 May 22 16:03",
        "max_defer_fail_percentage": "unlimited",
        "disklimit": "unlimited",
        "is_locked": 0,
        "suspendtime": null,
        "email": "user@example.com",
        "domain": "example.com",
        "unix_startdate": 1369256589,
        "user": "user",
        "plan": "extensions_user_user",
        "shell": "/bin/bash",
        "maxpop": "unlimited",
        "backup": 0,
        "theme": "paper_lantern",
        "owner": "root",
        "max_email_per_hour": "unlimited",
        "ipv6": [
           
        ],
        "suspendreason": "not suspended",
        "maxlst": "unlimited",
        "suspended": 0,
        "maxsql": "unlimited",
        "maxparked": "unlimited",
        "partition": "home",
        "maxsub": "unlimited"
      }
    ]
  },
  "metadata": {
    "version": 1,
    "reason": "OK",
    "result": 1,
    "command": "accountsummary"
  }
}
Localtab
titleXML
Tip
titleRemember:

Multiexcerpt include
MultiExcerptNameShort Warning
PageWithExcerptLIB:_XMLDeprecated
 

Code Block
languagexml
linenumberstrue
<result>
    <data>
        <acct>
            <maxaddons>unlimited</maxaddons>
            <ip>10.215.214.95</ip>
            <min_defer_fail_to_trigger_protection>5</min_defer_fail_to_trigger_protection>
            <legacy_backup>0</legacy_backup>
            <diskused>14M</diskused>
            <maxftp>unlimited</maxftp>
            <startdate>13 May 22 16:03</startdate>
            <max_defer_fail_percentage>unlimited</max_defer_fail_percentage>
            <disklimit>unlimited</disklimit>
            <is_locked>0</is_locked>
            <suspendtime/>
            <email>user@example.com</email>
            <domain>example.com</domain>
            <unix_startdate>1369256589</unix_startdate>
            <user>user</user>
            <plan>extensions_user_user</plan>
            <shell>/bin/bash</shell>
            <maxpop>unlimited</maxpop>
            <backup>0</backup>
            <theme>paper_lantern</theme>
            <owner>root</owner>
            <max_email_per_hour>unlimited</max_email_per_hour>
            <suspendreason>not suspended</suspendreason>
            <maxlst>unlimited</maxlst>
            <suspended>0</suspended>
            <maxsql>unlimited</maxsql>
            <maxparked>unlimited</maxparked>
            <partition>home</partition>
            <maxsub>unlimited</maxsub>
        </acct>
    </data>
    <metadata>
        <version>1</version>
        <reason>OK</reason>
        <result>1</result>
        <command>accountsummary</command>
    </metadata>
</result>