# 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 -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 -X POST -H "Content-Type: application/json" \
        -d '{"data": [ ] }' \
	https://bmc/logout

(or just delete your cookie jar file)

## HTTP GET operations & URL structure

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:

        $ 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"
        }

 - 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 `/enumerate` 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.
These require a json formatted payload. To get an example of what that looks
like:

    curl -b cjar -k \
        https://bmc/org/openbmc/control/flash/bios > bios.json

or

    curl -b cjar -k \
        https://bmc/org/openbmc/control/flash/bios/attr/flasher_path > flasher_path.json

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 -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).

These also require a json formatted payload.

To invoke a method with parameters:

    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


## 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.Delet`e is not implemented, the REST server will return a
HTTP 403 (Forbidden) error.

For example, to delete the event record with ID 0:

   curl -b cjar -k -X DELETE \
       https://bmc/org/openbmc/events/record/0