Interfacing with a RESTCONF API

This is about consuming a RESTCONF API, not building one. In short, if you know REST, you know RESTCONF. There are some incredible bonus features however that should useful and a few conventions that would be good to learn.

Methods

No surprises here:

• GET - Getting read-write data (e.g. config), read-only data (e.g. metrics) and getting events in SSE format detailed later in this document.
• PUT - Updating read-write data (e.g. config). If objects are not found, they will be created so this is really an upsert.
• POST - Creating read-write data (e.g. config). If objects are not found, you will get an error.
• DELETE - Deleting read-write data. If objects are not found, you will not get an error.
• OPTIONS - Useful to test if user has access to certain data path

URL

Basic for is this : /restconf/data/{module}:{path}[?params]

• module - name of the yang file So car.yang would be served at /restconf/data/car:
• path - drill down into the objects. So to access the car tires, would be /restconf/data/car:tires. Only tricky part is drilling into lists. If you wanted to drill into front-left tire, you might use /restconf/data/car:tires=front-left. Drilling deeper still might be /restconf/data/car:tires=front-left/vendor
• ?params - For GET methods only, many params will help you limit the amount of data you return to save bandwidth and compute resources. More detailed information can be found in the specification but here is a quick summary:
  • depth=N - limits the level of data returns to N levels in the hierarchy
  • content=config - return only configuration data
  • content=nonconfig - return only metric data
  • with-defaults=trim - Do not return leaf values if they match the default value. This is useful for determining what a configuration user may have actually changed versus what configuration a device is actually using.
  • fields=a;b/c - returns only select data paths. Note: you'll need to encode parameters depending on your http client libraries. For example this would be fields=a%3db/c
  • fc.xfields=a;b/c - inverse of fields in that it returns all fields except specified. Again watch the encoding of the ; as detailed above.
  • fc.range=b/c!N-M - returns rows N thru M inclusive in list b/c
  • fc.max-node-count=N - increases or decreases the maximum allowed data to be returned. There are limits by default to ensure unbounded requests do not bog down system.

Examples

See specification for more details on how RESTCONF maps to REST.

Task	Method	Path	Description
Read	GET	/restconf/data/car:	Get's all data (configuration and metrics) for car module
Read	GET	/restconf/data/car:tire	Get's all data for all tires
Read	GET	/restconf/data/car:tire=1	Get's all data for first car tire. Yes, seeing an equals in a URL can be disconcerting, but it is legal.
Update	PUT	/restconf/data/car:cruise body:{"desiredSpeed":65}	Set cruise control desired speed
Read	GET	/restconf/data/car:tire?c2-range=!1-2	Get's all data for car tires 1 and 2
Read	GET	/restconf/data/car:tire?fields=wear%3did	Get's only tire id and wear level for all tires. %3d is encoded =.
Read	GET	/restconf/data/car:tire?content=config&with-defaults=trim	Get's only configuration that is changed from the default for all tires
Create	POST	/restconf/data/car:navigate body:{"destination":{"address":"10 Main st."}}	Add a new destination address to navigation. This would only work if no naviation address was already set.
Delete	DELETE	/restconf/data/car:navigate/destination	Remove destination from navigation system.
RPC	POST	/restconf/data/car:rotateTires	Run a RPC to rotate the tires
RPC	POST	/restconf/data/car:rotateTires body:{"order":"clockwise"}	Run a RPC to rotate the tires in specific order
RPC	POST	/restconf/data/car:rotateTires body:{"order":"clockwise"} response:{"charge":30.00}	Run a RPC to rotate the tires in specific order and return the cost.
Event Stream	GET	/restconf/data/car: response: {"status":"running"} {"status":"stopped","reason":"flat"}	Stream of events regarding the car status
Event Stream	GET	/restconf/data/car:?filter=status%3dstopped response: {"status":"stopped","reason":"flat"}	Stream only events that cause car to stop. %3d is encoded =.

SUPER BONUS: Getting meta data

You can get any schema in JSON form. This is so handy, you will wonder how you ever worked without it. With this, you can build "model-assisted" user interfaces. For example:

1. all available options in a select list
2. all the available columns in a table
3. descriptions and lists of all fields
4. Data types for all fields.
5. You can even invent your own extensions to associate with any part of the schema, e.g. fields that should be encrypted or not visible to the user.

To access the meta data, use the following URLs:

• /restconf/schema/{module} - Access to YANG files in JSON resolved form
• /restconf/schema/{module}.yang - Access to YANG files in original YANG format