1# OpenBMC REST API 2 3The primary management interface for OpenBMC is REST. This document provides 4some basic structure and usage examples for the REST interface. 5 6The schema for the rest interface is directly defined by the OpenBMC dbus 7structure. Therefore, the objects, attributes and methods closely map to those 8in the dbus schema. 9 10For a quick explanation of HTTP verbs and how they relate to a RESTful API, see 11<http://www.restapitutorial.com/lessons/httpmethods.html>. 12 13## Logging in 14 15Before you can do anything you first need to log in: 16 17 curl -c cjar -k -X POST -H "Content-Type: application/json" \ 18 -d '{"data": [ "root", "0penBmc" ] }' \ 19 https://bmc/login 20 21 22This performs a login using the provided username and password, and stores the 23newly-acquired authentication credentials in the `curl` "Cookie jar" file (named 24`cjar` in this example). We will use this file (with the `-b` argument) for 25future requests. 26 27To log out: 28 29 curl -c cjar -b cjar -k -X POST -H "Content-Type: application/json" \ 30 -d '{"data": [ ] }' \ 31 https://bmc/logout 32 33(or just delete your cookie jar file) 34 35## HTTP GET operations & URL structure 36 37There are a few conventions on the URL structure of the OpenBMC rest interface. 38They are: 39 40 - To query the attributes of an object, perform a GET request on the object 41 name, with no trailing slash. For example: 42 43 $ curl -b cjar -k https://bmc/org/openbmc/inventory/system 44 { 45 "data": { 46 "Asset Tag": [], 47 "Custom Field 1": "\tbuildroot-dcb6dc3", 48 "Custom Field 2": "\tskiboot-5.1.15", 49 "Custom Field 3": "\thostboot-c223637-017f5fd", 50 "Custom Field 4": "\tlinux-4.4.6-openpower1-2291fe8", 51 "Custom Field 5": "\tpetitboot-72928ed-a75299d", 52 "Custom Field 6": "\tpalmetto-xml-8281868-6b8b2bb", 53 "Custom Field 7": "\tocc-1093bf9", 54 "Custom Field 8": "\thostboot-binaries-7f593a3", 55 "FRU File ID": [], 56 "Manufacturer": [], 57 "Model Number": [], 58 "Name": "OpenPOWER Firmware", 59 "Serial Number": [], 60 "Version": "open-power-palmetto-5a4a3d9", 61 "fault": "False", 62 "fru_type": "SYSTEM", 63 "is_fru": 1, 64 "present": "False", 65 "version": "" 66 }, 67 "message": "200 OK", 68 "status": "ok" 69 } 70 71 - To query a single attribute, use the `attr/<name>` path. Using the 72 `system` object from above, we can query just the `Name` value: 73 74 $ curl -b cjar -k https://bmc/org/openbmc/inventory/system/attr/Name 75 { 76 "data": "OpenPOWER Firmware", 77 "message": "200 OK", 78 "status": "ok" 79 } 80 81 - When a path has a trailing-slash, the response will list the sub objects of 82 the URL. For example, using the same object path as above, but adding a 83 slash: 84 85 $ curl -b cjar -k https://bmc/org/openbmc/inventory/system/ 86 { 87 "data": [ 88 "/org/openbmc/inventory/system/systemevent", 89 "/org/openbmc/inventory/system/chassis" 90 ], 91 "message": "200 OK", 92 "status": "ok" 93 } 94 95 This shows that there are two children of the `system/` object: `systemevent` 96 and `chassis`. This can be used with the base REST URL (ie., `http://bmc/`), 97 to discover all objects in the hierarchy. 98 99 - Performing the same query with `/list` will list the child objects 100 *recursively*. 101 102 $ curl -b cjar -k https://palm5-bmc/list 103 [output omitted] 104 105 - Adding `/emumerate` instead of `/list` will also include the attributes of 106 the listed objects. 107 108 109## HTTP PUT operations 110 111PUT operations are for updating an existing resource (an object or property), or 112for creating a new resource when the client already knows where to put it. 113These require a json formatted payload. To get an example of what that looks 114like: 115 116 curl -b cjar -k \ 117 https://bmc/org/openbmc/control/flash/bios > bios.json 118 119or 120 121 curl -b cjar -k \ 122 https://bmc/org/openbmc/control/flash/bios/attr/flasher_path > flasher_path.json 123 124When turning around and sending these as requests, delete the message and status 125properties. 126 127To make curl use the correct content type header use the -H option to specify 128that we're sending JSON data: 129 130 curl -b cjar -k -H "Content-Type: application/json" -X POST -d <json> <url> 131 132A PUT operation on an object requires a complete object. For partial updates 133there is PATCH but that is not implemented yet. As a workaround individual 134attributes are PUTable. 135 136For example, make changes to the file and do a PUT (upload): 137 138 139 curl -b cjar -k -H "Content-Type: application/json" \ 140 -X PUT -T bios.json \ 141 https://bmc/org/openbmc/control/flash/bios 142 143 curl -b cjar -k -H "Content-Type: application/json" \ 144 -X PUT -T flasher_path.json \ 145 https://bmc/org/openbmc/control/flash/bios/attr/flasher_path 146 147 148Alternatively specify the json inline with -d: 149 150 curl -b cjar -k -H "Content-Type: application/json" -X PUT 151 -d '{"data": <value>}' \ 152 https://bmc/org/openbmc/control/flash/bios/attr/flasher_path 153 154When using '-d' Just remember that json requires quoting. 155 156## HTTP POST operations 157POST operations are for calling methods, but also for creating new resources 158when the client doesn't know where to put it. OpenBMC does not support creating 159new resources via REST so any attempt to create a new resource will result in a 160HTTP 403 (Forbidden). 161 162These also require a json formatted payload. 163 164To invoke a method with parameters: 165 166 curl -b cjar -k -H "Content-Type: application/json" -X POST \ 167 -d '{"data": [<positional-parameters>]}' \ 168 https://bmc/org/openbmc/control/fan0/action/setspeed 169 170To invoke a method without parameters: 171 172 curl -c cjar -b cjar -k -H "Content-Type: application/json" -X POST \ 173 -d '{"data": []}' \ 174 https://bmc/org/openbmc/control/fan0/action/getspeed 175 176 177## HTTP DELETE operations 178DELETE operations are for removing instances. Only DBUS objects (instances) can 179be removed. If the underlying DBUS object implements the 180`org.openbmc.Object.Delete` interface the REST server will call it. If 181`org.openbmc.Object.Delet`e is not implemented, the REST server will return a 182HTTP 403 (Forbidden) error. 183 184For example, to delete the event record with ID 0: 185 186 curl -b cjar -k -X DELETE \ 187 https://bmc/org/openbmc/events/record/0 188 189