rest-api: Restructure and expand, and improve example code
This change restructures the rest-api document a little, so that it's
more in a manual format.
Also, we simplify the command-line examples a little, by only providing
the cjar-specific options where required; use single-quoting to avoid
lots of shell escaping; add command output where suitable, and wrap to
prevent long lines.
Signed-off-by: Jeremy Kerr <jk@ozlabs.org>
diff --git a/rest-api.md b/rest-api.md
index 935c929..d0be259 100644
--- a/rest-api.md
+++ b/rest-api.md
@@ -1,119 +1,188 @@
# OpenBMC REST API
+The primary management interface for OpenBMC is REST. This document provides
+some basic structure and usage examples for the REST interface.
+
+The schema for the rest interface is directly defined by the OpenBMC dbus
+structure. Therefore, the objects, attributes and methods closely map to those
+in the dbus schema.
+
+For a quick explanation of HTTP verbs and how they relate to a RESTful API, see
+<http://www.restapitutorial.com/lessons/httpmethods.html>.
+
## Logging in
+
Before you can do anything you first need to log in:
-```
-curl -c cjar -b cjar -k -H "Content-Type: application/json" -X POST https://bmc/login -d "{\"data\": [ \"root\", \"0penBmc\" ] }"
-```
+
+ curl -c cjar -k -X POST -H "Content-Type: application/json" \
+ -d '{"data": [ "root", "0penBmc" ] }' \
+ https://bmc/login
+
+
+This performs a login using the provided username and password, and stores the
+newly-acquired authentication credentials in the `curl` "Cookie jar" file (named
+`cjar` in this example). We will use this file (with the `-b` argument) for
+future requests.
To log out:
-```
-curl -c cjar -b cjar -k -H "Content-Type: application/json" -X POST https://bmc/logout -d "{\"data\": [ ] }"
-```
-You need to use the provided cookie on any subsequent requests with the -c and -b options.
+ curl -c cjar -b cjar -k -X POST -H "Content-Type: application/json" \
+ -d '{"data": [ ] }' \
+ https://bmc/logout
-## HTTP GET operations
-List directory:
-```
-curl -c cjar -b cjar -k https://bmc/<path>/
-```
-Examples:
-```
-curl -c cjar -b cjar -k https://bmc/
-curl -c cjar -b cjar -k https://bmc/org/
-curl -c cjar -b cjar -k https://bmc/org/openbmc/
-curl -c cjar -b cjar -k https://bmc/org/openbmc/inventory/
-curl -c cjar -b cjar -k https://bmc/org/openbmc/inventory/system/chassis/
-```
+(or just delete your cookie jar file)
-List objects recursively:
-```
-curl -c cjar -b cjar -k https://bmc/<path>/list
-```
-Examples:
-```
-curl -c cjar -b cjar -k https://bmc/list
-curl -c cjar -b cjar -k https://bmc/org/openbmc/inventory/list
-```
+## HTTP GET operations & URL structure
-Enumerate objects recursively:
-```
-curl -c cjar -b cjar -k https://bmc/<path>/enumerate
-```
-Examples:
-```
-curl -c cjar -b cjar -k https://bmc/enumerate
-curl -c cjar -b cjar -k https://bmc/org/openbmc/inventory/enumerate
+There are a few conventions on the URL structure of the OpenBMC rest interface.
+They are:
-```
+ - To query the attributes of an object, perform a GET request on the object
+ name, with no trailing slash. For example:
-Get object:
-```
-curl -c cjar -b cjar -k https://bmc/<path>
-```
-Examples:
-```
-curl -c cjar -b cjar -k https://bmc/org/openbmc/inventory/system/chassis/fan2
-```
+ $ curl -b cjar -k https://bmc/org/openbmc/inventory/system
+ {
+ "data": {
+ "Asset Tag": [],
+ "Custom Field 1": "\tbuildroot-dcb6dc3",
+ "Custom Field 2": "\tskiboot-5.1.15",
+ "Custom Field 3": "\thostboot-c223637-017f5fd",
+ "Custom Field 4": "\tlinux-4.4.6-openpower1-2291fe8",
+ "Custom Field 5": "\tpetitboot-72928ed-a75299d",
+ "Custom Field 6": "\tpalmetto-xml-8281868-6b8b2bb",
+ "Custom Field 7": "\tocc-1093bf9",
+ "Custom Field 8": "\thostboot-binaries-7f593a3",
+ "FRU File ID": [],
+ "Manufacturer": [],
+ "Model Number": [],
+ "Name": "OpenPOWER Firmware",
+ "Serial Number": [],
+ "Version": "open-power-palmetto-5a4a3d9",
+ "fault": "False",
+ "fru_type": "SYSTEM",
+ "is_fru": 1,
+ "present": "False",
+ "version": ""
+ },
+ "message": "200 OK",
+ "status": "ok"
+ }
-Get property:
-```
-curl -c cjar -b cjar -k https://bmc/<path>/attr/<attr>
-curl -c cjar -b cjar -k https://bmc/org/openbmc/inventory/system/chassis/fan2/attr/is_fru
-```
+ - To query a single attribute, use the `attr/<name>` path. Using the
+ `system` object from above, we can query just the `Name` value:
+
+ $ curl -b cjar -k https://bmc/org/openbmc/inventory/system/attr/Name
+ {
+ "data": "OpenPOWER Firmware",
+ "message": "200 OK",
+ "status": "ok"
+ }
+
+ - When a path has a trailing-slash, the response will list the sub objects of
+ the URL. For example, using the same object path as above, but adding a
+ slash:
+
+ $ curl -b cjar -k https://bmc/org/openbmc/inventory/system/
+ {
+ "data": [
+ "/org/openbmc/inventory/system/systemevent",
+ "/org/openbmc/inventory/system/chassis"
+ ],
+ "message": "200 OK",
+ "status": "ok"
+ }
+
+ This shows that there are two children of the `system/` object: `systemevent`
+ and `chassis`. This can be used with the base REST URL (ie., `http://bmc/`),
+ to discover all objects in the hierarchy.
+
+ - Performing the same query with `/list` will list the child objects
+ *recursively*.
+
+ $ curl -b cjar -k https://palm5-bmc/list
+ [output omitted]
+
+ - Adding `/emumerate` instead of `/list` will also include the attributes of
+ the listed objects.
+
## HTTP PUT operations
-PUT operations are for updating an existing resource ( an object or property ), or for creating a new resource when the client already knows where to put it.
-For a quick explanation of HTTP verbs and how they relate to a RESTful API see this page:
-```
-http://www.restapitutorial.com/lessons/httpmethods.html
-```
-These require a json formatted payload. To get an example of what that looks like:
-```
-curl -c cjar -b cjar -k https://bmc/org/openbmc/control/flash/bios > bios.json # - or -
-curl -c cjar -b cjar -k https://bmc/org/openbmc/control/flash/bios/attr/flasher_path > flasher_path.json
-```
+PUT operations are for updating an existing resource (an object or property), or
+for creating a new resource when the client already knows where to put it.
+These require a json formatted payload. To get an example of what that looks
+like:
-When turning around and sending these as requests, delete the message and status properties.
+ curl -b cjar -k \
+ https://bmc/org/openbmc/control/flash/bios > bios.json
-To make curl use the correct content type header use the -H option:
-```
-curl -c cjar -b cjar -k -H "Content-Type: application/json" -X POST -d <json> <url>
-```
-A put operation on an object requires a complete object. For partial updates there is PATCH but that is not implemented yet. As a workaround individual attributes are PUTable.
+or
-Make changes to the file and do a put (upload):
+ curl -b cjar -k \
+ https://bmc/org/openbmc/control/flash/bios/attr/flasher_path > flasher_path.json
-```
-curl -c cjar -b cjar -k -H "Content-Type: application/json" -X PUT -T bios.json https://bmc/org/openbmc/control/flash/bios
-curl -c cjar -b cjar -k -H "Content-Type: application/json" -X PUT -T flasher_path.json https://bmc/org/openbmc/control/flash/bios/attr/flasher_path
-```
+When turning around and sending these as requests, delete the message and status
+properties.
+
+To make curl use the correct content type header use the -H option to specify
+that we're sending JSON data:
+
+ curl -b cjar -k -H "Content-Type: application/json" -X POST -d <json> <url>
+
+A PUT operation on an object requires a complete object. For partial updates
+there is PATCH but that is not implemented yet. As a workaround individual
+attributes are PUTable.
+
+For example, make changes to the file and do a PUT (upload):
+
+
+ curl -b cjar -k -H "Content-Type: application/json" \
+ -X PUT -T bios.json \
+ https://bmc/org/openbmc/control/flash/bios
+
+ curl -b cjar -k -H "Content-Type: application/json" \
+ -X PUT -T flasher_path.json \
+ https://bmc/org/openbmc/control/flash/bios/attr/flasher_path
+
Alternatively specify the json inline with -d:
-```
-curl -c cjar -b cjar -k -H "Content-Type: application/json" -X PUT -d "{\"data\": <value>}" flasher_path.json https://bmc/org/openbmc/control/flash/bios/attr/flasher_path
-```
-When using '-d' Just remember that json requires double quotes and any shell metacharacters need to be escaped.
+ curl -b cjar -k -H "Content-Type: application/json" -X PUT
+ -d '{"data": <value>}' \
+ https://bmc/org/openbmc/control/flash/bios/attr/flasher_path
+
+When using '-d' Just remember that json requires quoting.
## HTTP POST operations
-POST operations are for calling methods, but also for creating new resources when the client doesn't know where to put it. OpenBMC does not support creating new resources via REST so any attempt to create a new resource will result in a HTTP 403 ( Forbidden ).
+POST operations are for calling methods, but also for creating new resources
+when the client doesn't know where to put it. OpenBMC does not support creating
+new resources via REST so any attempt to create a new resource will result in a
+HTTP 403 (Forbidden).
+
These also require a json formatted payload.
To invoke a method with parameters:
-```
-curl -c cjar -b cjar -k -H "Content-Type: application/json" -X POST -d "{\"data\": [<positional-parameters>]}" https://bmc/org/openbmc/control/fan0/action/setspeed
-```
+
+ curl -b cjar -k -H "Content-Type: application/json" -X POST \
+ -d '{"data": [<positional-parameters>]}' \
+ https://bmc/org/openbmc/control/fan0/action/setspeed
+
To invoke a method without parameters:
-```
-curl -c cjar -b cjar -k -H "Content-Type: application/json" -X POST -d "{\"data\": []}" https://bmc/org/openbmc/control/fan0/action/getspeed
-```
+
+ curl -c cjar -b cjar -k -H "Content-Type: application/json" -X POST \
+ -d '{"data": []}' \
+ https://bmc/org/openbmc/control/fan0/action/getspeed
+
## HTTP DELETE operations
-DELETE operations are for removing instances. Only DBUS objects (instances) can be removed. If the underlying DBUS object implements the org.openbmc.Object.Delete interface the REST server will call it. If org.openbmc.Object.Delete is not implemented, HTTP 403 will be returned.
+DELETE operations are for removing instances. Only DBUS objects (instances) can
+be removed. If the underlying DBUS object implements the
+`org.openbmc.Object.Delete` interface the REST server will call it. If
+`org.openbmc.Object.Delet`e is not implemented, the REST server will return a
+HTTP 403 (Forbidden) error.
-```
-curl -c cjar -b cjar -k -X DELETE https://bmc/org/openbmc/events/record/0
-```
+For example, to delete the event record with ID 0:
+
+ curl -b cjar -k -X DELETE \
+ https://bmc/org/openbmc/events/record/0
+