xref: /openbmc/docs/rest-api.md (revision 8b80cb60) 
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 `/enumerate` 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