webinar: applying rest to network management – an implementor’s view

Applying REST to Network Management; An Implementor’s View

Carl Moberg, VP Technology [email protected] @cmoberg

Confidential Information | December 18, 2012

1

Agenda

•  Background and Overview of REST •  REST in a Network Management Context •  Introducing Data Models •  Putting it all Together •  A Short Demo


2

A Brief History of REST

•  Fielding, R. T. (2000) Architectural Styles and the Design of Network-based Software Architectures

•  Many called, few are chosen •  An architectural style... but we digress


3

Which Way to Slice This?

•  The REST Architectural Style describes six constraints: –  Uniform interface, Stateless, Cacheable, Client-server, Layered

System, Code on demand (optional)

•  Guiding principles for of a REST interface (the Uniform Interface constraints): –  Resources have unique identifiers (e.g. URIs) –  Manipulations of resources through representations –  Self-descriptive Messages –  Hypermedia as the engines of application state (HATEOAS)


4

Resources Have Unique Identifiers (e.g. URIs)

•  Individual resources are identified in requests using URIs •  Resources are conceptually separate from the

representations •  Resource representations depend on query and server

support (e.g. XML and JSON)


GET /api/running/interfaces/interface/eth0/ipv4 HTTP/1.1!!<ipv4 y:self="/api/running/interfaces/interface/eth0/ip:ipv4”>! <address y:self=”[...]">! <ip>192.168.0.1</ip>!...!!

5

Manipulation of Representations

•  Representations (including metadata) contain enough information to be modified or deleted

•  Provided that the client has permission to do so


< Content-Type: application/vnd.yang.data+xml!!<ipv4 y:self="/api/running/interfaces/interface/eth0/ip:ipv4”>! <address y:self=”[...]">! <ip>192.168.0.1</ip>! </address>!</ipv4>!

6

Self-descriptive Messages

•  Each message includes enough information to describe how to process the message

•  Foundation for stateless processing •  Standard methods and media types are used to indicate

semantics and exchange information


< HTTP/1.1 200 OK!< Server: ConfD!< Cache-control: private, no-cache, must-revalidate, proxy-revalidate!< Date: Tue, 18 Dec 2012 15:53:12 GMT!< Content-Type: application/vnd.yang.data+xml!< Transfer-Encoding: chunked!

7

Hypermedia as the Engines of Application State

•  Most profound (and abused) criteria •  Clients deliver state via contents, query-string parameters,

request headers and the URI •  Servers deliver state to clients via content, response codes,

and response headers •  ...just like the web works Confidential Information | December 18, 2012

<running y:self="/api/running"/>!!<interface y:self="/api/running/interfaces/interface/eth0">!!<lock y:self="/api/running/_lock">!!

A REST API must not define fixed resource names or hierarchies - (angry) Fielding on his blog

8

REST vs Other Protocols


REST SNMP NETCONF SOAP

Data models SNMP MIBs YANG Models

Data Modeling Language

SMI YANG WSDL

Management Operations

HTTP Verbs SNMP Operations

NETCONF Operations

N/A

RPC Protocol Encoding

HTTP/XML/JSON

BER XML XML

Transport Stack

SSL/HTTP/TCP

UDP SSH/TCP SSL/HTTP/TCP

9

REST in a Network Management Context

•  We will focus on using REST to read and write data to network elements

•  Most applications we’ve come across expect to use RESTful HTTP to extract data using simple scripts –  curl(1), wget(1)

•  As mentioned, we manipulate resources, one at a time •  But we know people will try and use it to peek and poke


Recommended reading: RFC 3535 Overview of the 2002 IAB Network Management Workshop

10

Information Models and Data Models

•  Information Models are conceptual, implementation independent

•  Data Models are detailed, intended for implementations


Recommended reading: RFC 3444 On the difference between Information Models and Data Models

Information Model

Data Model Data Model Data Model

Examples: UML, Entity Relations (ER)

Examples: SMI, WSDL, YANG

11

Data Models in Network Management

•  So, what is the data model of a router or a switch? –  For OpenFlow people, it’s the switch pipeline –  For I2RS people, it’s the FIB and RIB –  For most implementations in the field, it’s what’s in the CLI

•  Well used CLIs exhibit the inherited characteristics of all use cases it’s been exposed to

•  We’ll assume (and it’s relatively well founded) that REST APIs want to be on the same abstraction level as the CLI –  Also, reality (code base) prohibits much else –  REST on a network level is very interesting, but different


12

The YANG Data Modeling Language

•  IETF RFC 6020, Standards Track •  A Language designed to write data

models for the NETCONF protocol. It provides features including: –  Human readable –  Hierarchical –  Reusable types and groupings –  Extensibility –  Formal constraints for validation

•  Proven to be useful for other applications (CLI, Web UI, etc)

13

Example Data Model in YANG


interfaces

statistics

ipv4

ipv6

interface key: name

address address

address address

•  We’ll be looking at –  ietf-interface.yang!–  ietf-ip.yang!

•  Developed in the IETF NETMOD WG

•  More models in the making

14

Mapping YANG to REST Resources

•  YANG data nodes are mapped to REST resources •  YANG rpc statements are mapped to HTTP POST

operations •  HTTP Verbs:

–  GET to fetch resources –  POST to create resources –  PUT to replace a resource –  PATCH to modify existing resources –  DELETE to remove resources


15

An Example Query (An Ethernet Interface)

> GET /api/running/interfaces/interface/eth0 HTTP/1.1!> Authorization: Basic YWRtaW46YWRtaW4=!> User-Agent: curl/7.28.!> Host: 127.0.0.1:8008!> Accept: */*!> !< HTTP/1.1 200 OK!< Server: ConfD!< Date: Mon, 17 Dec 2012 16:08:33 GMT!< Content-Type: application/vnd.yang.data+xml!< Transfer-Encoding: chunked!< !!<interface y:self="/api/running/interfaces/interface/eth0”>! <name>eth0</name>! <type>ethernetCsmacd</type>! <location>0</location>! <ipv4 xmlns="urn:ietf:params:xml:ns:yang:ietf-ip">! <address y:self="/api/running/interfaces/interface/eth0/ip:ipv4/address/192.168.0.1">! <ip>192.168.0.1</ip>! </address>! </ipv4>! <ethernet xmlns="http://example.com/ethernet">! </ethernet>!</interface>!!


1

2

3

16

Introducing ConfD and it's REST Interface


ConfD Core Engine •  Transactions •  AAA/User Sessions •  Logs and audit trails

REST NETCONF

Managed Objects API

CDB YANG Module

Managed Object Managed

Object

Managed Object Managed

Object

NETCONF SNMP Web UI

17

How Does REST Work in a ConfD Context

•  Just another northbound interface, shared everything •  RESTful API over HTTP

–  for accessing data defined in YANG, stored in CDB –  using the datastores as defined in NETCONF

•  Configuration data and state data are exposed to GET •  Configuration data also accept DELETE PATCH POST and

PUT


18

REST Resources (Top Level)

•  Top level resource application/vnd.yang.api

–  Well known /api location –  version string –  running - the running datastore –  operational - the representation of all operational data


19

REST Resources (Datastores)

•  Datastores application/vnd.yang.datastore –  running - The running configuration of the device –  startup - The startup configuration of the device


20

Rest Resources (Model Resources)

•  Model Resources application/vnd.yang.data –  All resources has y:path and y:self in representation –  All subresources has y:self reference


21

(Finally) Time for Demo

•  Queries –  Top-level –  Datastores –  Operations

•  Interface configuration –  Look at interfaces –  Change IP address


22

Conclusions and Things to Ponder

•  REST allows for easy scripting with existing tools –  Many command line tools available and default on Linux and Mac –  Many, many language bindings

•  REST does not provide sessions: –  Impact on error management –  How about transactions

•  Rest allows for changing a single resource at a time: –  How does this scale in multi-parameter, complex environment


23

Wrap up and Questions

•  Suggested reading list: –  Fielding Dissertation –  RFC 3535 –  RFC 3444 –  YANG-API Protocol Draft (draft-bierman-netconf-yang-api-01)

•  Discuss! –  @cmoberg –  [email protected]
