1# Redfish Coding Guidelines
2
3- For robot programs wishing to run Redfish commands, include the following in
4  your robot file:
5
6  ```
7  *** Settings ***
8
9  Resource                    bmc_redfish_resource.robot
10  ```
11
12- This git repository has some redfish wrapper modules:
13
14  - [redfish_plus.py](../lib/redfish_plus.py)
15  - [bmc_redfish.py](../lib/bmc_redfish.py)
16  - [bmc_redfish_utils.py](../lib/bmc_redfish_utils.py)
17  - Redfish wrapper module features:
18
19    For all Redfish REST requests (get, head, post, put, patch, delete):
20
21    - Support for python-like strings for all arguments which allows callers to
22      easily specify complex arguments such as lists or dictionaries.
23
24      So instead of coding this:
25
26      ```
27          ${ldap_type_dict}=  Create Dictionary  ServiceEnabled=${False}
28          ${body}=  Create Dictionary  ${LDAP_TYPE}=${ldap_type_dict}
29          Redfish.Patch  ${REDFISH_BASE_URI}AccountService  body=${body}
30      ```
31
32      You can do it in one fell swoop like this:
33
34      ```
35          Redfish.Patch  ${REDFISH_BASE_URI}AccountService  body={'${LDAP_TYPE}': {'ServiceEnabled': ${False}}}
36      ```
37
38    - Support for **valid_status_codes** argument and auto-failure:
39
40      As mentioned above, this argument may be either an actual robot/python
41      list or it may be a string value which python can translate into a list.
42
43      The default value is [${HTTP_OK}].
44
45      This means that the Redfish REST request will fail **automatically** if
46      the resulting status code is not found in the valid_status_codes list.
47
48      So instead of having to do this:
49
50      ```
51          ${resp}=  Redfish.Get  ${EVENT_LOG_URI}Entries
52          Should Be Equal As Strings  ${resp.status_code}  ${HTTP_OK}
53      ```
54
55      You can simply do this:
56
57      ```
58          ${resp}=  Redfish.Get  ${EVENT_LOG_URI}Entries
59      ```
60
61      If, for some reason, you **expect** your command to fail, you can specify
62      the expected status code or codes:
63
64      ```
65      Redfish.Patch  ${REDFISH_BASE_URI}UpdateService  body={'ApplyTime' : 'Invalid'}  valid_status_codes=[${HTTP_BAD_REQUEST}]
66      ```
67
68  - Login defaults for path, username and password are
69    https://${OPENBMC_HOST},
70    ${OPENBMC_USERNAME}, ${OPENBMC_PASSWORD}.
71  - Many utility functions are available. Examples:;
72
73    - get_properties
74    - get_attributes
75    - get_session_info
76    - list_request
77    - enumerate_request
78
79# Rules for use of Redfish.Login and Redfish.Logout
80
81It is desirable to avoid excessive redfish logins/logouts for the following
82reasons:
83
84- It simplifies the code base.
85- It allows calling keywords and testcases to keep control over login parameters
86  like USERNAME, PASSWORD, etc. Consider the following example:
87
88  ```
89  # Login to redfish with non-standard username/password.
90  Redfish.Login  ${LDAP_USER}  ${LDAP_USER_PASSWORD}
91  # Run 'Some Keyword' while logged in as ${LDAP_USER}/${LDAP_USER_PASSWORD}.
92  Some Keyword
93  ```
94
95  If 'Some Keyword' in the example above does its own Redfish.Login, it will
96  thwart the stated purpose of the caller.
97
98**Rules:**
99
100- Login should be done once in Suite Setup:
101
102  ```
103  *** Keywords ***
104  Suite Setup Execution
105      Redfish.Login
106  ```
107
108- Logout should be done once in Suite Teardown:
109  ```
110  *** Keywords ***
111  Suite Teardown Execution
112      Redfish.Logout
113  ```
114- As a result of the first two rules, all keywords and testcases that call upon
115  redfish functions (e.g. Redfish.Get, Redfish.Patch, etc.) have a right to
116  expect that login/logout have already been handled. Therefore, such keywords
117  and testcases should NOT do logins and logouts themselves.
118- There may be exceptions to the above but they require justification (e.g. a
119  test whose purpose is to verify that it can login with an **alternate**
120  username, etc.).
121- Any keyword or test case which breaks the above rules is responsible for
122  setting things right (i.e. back to a logged in state).
123
124# Rules for use of data/variables.py
125
126Avoid defining variables in data/variables.py for Redfish URIs.
127
128There's no obvious benefit to using such variables. Conversely, with literal
129values, it is much easier for the programmer to interpret the code.
130
131Consider the following example.
132
133Here's an excerpt from data/variables.py:
134
135```
136# Redfish variables.
137REDFISH_BASE_URI = '/redfish/v1/'
138...
139REDFISH_ACCOUNTS = 'AccountService/Accounts/'
140REDFISH_ACCOUNTS_URI = REDFISH_BASE_URI + REDFISH_ACCOUNTS
141```
142
143And here is a corresponding Robot code example:
144
145```
146    # Rather than coding this:
147    Redfish.Delete  ${REDFISH_ACCOUNTS_URI}user_user
148
149    # Code this:
150    Redfish.Delete  /redfish/v1/AccountService/Accounts/user_user
151```
152