文档中心
Web REST API Mapping Configuration Guide
更新时间： 2025/08/18
在Gitcode上查看源码

The Web REST APIs of the openUBMC community are implemented using mapping solutions, which require commands to be configured in the JSON file. The mapping configuration file of Web REST APIs is in the web_backend directory of the rackmount code repository.

API URI ​

  • URI format
shell
/UI/Rest/<resource>

  • Supported request types GET POST PATCH DELETE

  • Precautions Most Web REST API URIs are fixed strings and do not require validity verification, except those with dynamic parameters. For example, in /UI/Rest/AccessMgnt/Accounts/Account_ID/ImportSSHPublicKey, Account_ID is a dynamic parameter and obtained only when the request is received, which requires verification.

Configuration Example ​

For details about how to configure the data mapper of the Web REST APIs, see Interface Mapping Configuration.

json
{
    "Uri": "/UI/Rest/BMCSettings/Language/OpenLanuage",
    "Interfaces": [
        {
            "Type": "POST",
            "ReqBody": [
                {
                    "Name": "LanguageSetStr",
                    "Type": "String"
                }
            ],
            "RspBody": {
                "LanguageSet": "${Statements/LanguageSetRsp()}"
            },
            "Statements": {
                "LanguageSet": {
                    "Input": "${ProcessingFlow[1]/Destination/LanguageSet}",
                    "Steps": [
                        {
                            "Type": "Script",
                            "Formula": "Input[#Input + 1] = 'add' .. ReqBody.LanguageSetStr return Input"
                        }
                    ]
                },
                "LanguageSetRsp": {
                    "Input": "/bmc/kepler/Systems/1/Product",
                    "Steps": [
                        {
                            "Type": "Expand",
                            "Formula": 1
                        }
                    ]
                }
            },
            "ProcessingFlow": [
                {
                    "Type": "Property",
                    "Path": "/bmc/kepler/Systems/1/Product",
                    "Interface": "bmc.kepler.Systems.Product",
                    "Destination": {
                        "LanguageSet": "LanguageSet"
                    }
                },
                {
                    "Type": "Property",
                    "Path": "/bmc/kepler/Systems/1/Product",
                    "Interface": "bmc.kepler.Systems.Product",
                    "Source": {
                        "LanguageSet": "${Statements/LanguageSet()}"
                    }
                }
            ]
        }
    ]
}

Specific Fields ​

Secondary Authentication ​

Some user- and security-related APIs require secondary web authentication, such as changing the VNC password, creating/deleting a user, modifying specified user information, adding/deleting an SSH public key, modifying permissions of a custom role, modifying a specified domain controller, modifying SNMPv3 encryption password information, adding/modifying/deleting LDAP and Kerberos user group information, importing LDAP certificates or certificate revocation lists (CRLs), importing Kerberos key tables, and importing configurations.

  • ReauthKey must be specified in the request body.
json
{
    "ReauthKey": value
}
  • The mapper configuration uses Reauth for secondary authentication declaration.
json
{
    "Resource": [
        {
            "Uri": "xxxx",
            "Interfaces": [
                {
                    "Type": "POST",
                    "ReqBody": [xxxx],
                    "Reauth": "${ReqBody/ReauthKey}",
                    "ProcessingFlow": [xxxx]
                }
            ]
        }
    ]
}

Error Message ​

The Redfish standard is used to define error messages of Web REST APIs. The Web REST APIs use the Code and Message fields in the standard error information to combine complete error information, and use the HttpStatusCode field to specify the response code. For example:

  • Standard error definition
json
"InsufficientPrivilege": {
    "Description": "Indicates that the credentials associated with the established session do not have sufficient privileges for the requested operation",
    "Message": "There are insufficient privileges for the account or credentials associated with the current session to perform the requested operation.",
    "Severity": "Critical",
    "NumberOfArgs": 0,
    "Resolution": "Either abandon the operation or change the associated access rights and resubmit the request if the operation failed.",
    "HttpStatusCode": 403,
    "IpmiCompletionCode": "0xFF",
    "SnmpStatusCode": 6,
    "TraceDepth": 0
}
  • **Combined error information and response code of Web REST **
json
{
    "error": [
        {
            "code": "InsufficientPrivilege",
            "message": "There are insufficient privileges for the account or credentials associated with the current session to perform the requested operation."
        }
    ]
}