Redfish Coding Guidelines
=========================

-   For robot programs wishing to run Redfish commands, include the following in
    your robot file:

    ```
    *** Settings ***

    Resource                    bmc_redfish_resource.robot
    ```
-   This git repository has some redfish wrapper modules:

    -   [redfish_plus.py](../lib/redfish_plus.py)
    -   [bmc_redfish.py](../lib/bmc_redfish.py)
    -   [bmc_redfish_utils.py](../lib/bmc_redfish_utils.py)
    -   Redfish wrapper module features:

        For all Redfish REST requests (get, head, post, put, patch, delete):

        -   Support for python-like strings for all arguments which allows
            callers to easily specify complex arguments such as lists or
            dictionaries.

            So instead of coding this:

            ```
                ${ldap_type_dict}=  Create Dictionary  ServiceEnabled=${False}
                ${body}=  Create Dictionary  ${LDAP_TYPE}=${ldap_type_dict}
                Redfish.Patch  ${REDFISH_BASE_URI}AccountService  body=${body}
            ```

            You can do it in one fell swoop like this:

            ```
                Redfish.Patch  ${REDFISH_BASE_URI}AccountService  body={'${LDAP_TYPE}': {'ServiceEnabled': ${False}}}
            ```
        -   Support for **valid_status_codes** argument and auto-failure:

            As mentioned above, this argument may be either an actual
            robot/python list or it may be a string value which python can
            translate into a list.

            The default value is [${HTTP_OK}].

            This means that the Redfish REST request will fail
            **automatically** if the resulting status code is not found in the
            valid_status_codes list.

            So instead of having to do this:

            ```
                ${resp}=  Redfish.Get  ${EVENT_LOG_URI}Entries
                Should Be Equal As Strings  ${resp.status_code}  ${HTTP_OK}
            ```

            You can simply do this:

            ```
                ${resp}=  Redfish.Get  ${EVENT_LOG_URI}Entries
            ```

            If, for some reason, you **expect** your command to fail, you can
            specify the expected status code or codes:

            ```
            Redfish.Patch  ${REDFISH_BASE_URI}UpdateService  body={'ApplyTime' : 'Invalid'}  valid_status_codes=[${HTTP_BAD_REQUEST}]
            ```
    -   Login defaults for path, username and password are
        https://${OPENBMC_HOST}, ${OPENBMC_USERNAME}, ${OPENBMC_PASSWORD}.
    -   Many utility functions are available.  Examples:;

        -   get_properties
        -   get_attributes
        -   get_session_info
        -   list_request
        -   enumerate_request

Rules for use of Redfish.Login and Redfish.Logout
=================================================

It is desirable to avoid excessive redfish logins/logouts for the following
reasons:
-	It simplifies the code base.
-	It allows calling keywords and testcases to keep control over login
    parameters like USERNAME, PASSWORD, etc.  Consider the following example:

    ```
    # Login to redfish with non-standard username/password.
    Redfish.Login  ${LDAP_USER}  ${LDAP_USER_PASSWORD}
    # Run 'Some Keyword' while logged in as ${LDAP_USER}/${LDAP_USER_PASSWORD}.
    Some Keyword
    ```
    If 'Some Keyword' in the example above does its own Redfish.Login, it will
    thwart the stated purpose of the caller.

**Rules:**

-   Login should be done once in Suite Setup:

    ```
    *** Keywords ***
    Suite Setup Execution
        Redfish.Login
    ```
-   Logout should be done once in Suite Teardown:
    ```
    *** Keywords ***
    Suite Teardown Execution
        Redfish.Logout
    ```
-   As a result of the first two rules, all keywords and testcases that call
    upon redfish functions (e.g. Redfish.Get, Redfish.Patch, etc.) have a right
    to expect that login/logout have already been handled.  Therefore, such
    keywords and testcases should NOT do logins and logouts themselves.
-   There may be exceptions to the above but they require justification (e.g. a
    test whose purpose is to verify that it can login with an **alternate**
    username, etc.).
-   Any keyword or test case which breaks the above rules is responsible for
    setting things right (i.e. back to a logged in state).