This webinar gives an introduction to the principles of REST, shows how it can be used to expose programmable APIs on network elements and provides some real world examples from our implementation. The principles of Representational State Transfer (REST) have gained a strong following since they were described by Roy Fielding in his doctoral dissertation written in 2000. REST’s strength lies in its scalability and generality, allowing it to be used for many types of applications. The industry has already seen a number of implementations of network management applications that use REST interfaces on the infrastructure management layer, notably OpenStack Quantum and the Sun Cloud API. As a vendor to the vendors, we’ve seen a significant increase in interest around having REST interfaces exposed directly on the network element, be they hardware based or virtual. http://www.tail-f.com

1. Applying REST to Network Management;
An Implementor’s View
Carl Moberg, VP Technology
calle@tail-f.com
@cmoberg
Confidential Information | December 18, 2012

2. Agenda
• Background and Overview of REST
• REST in a Network Management Context
• Introducing Data Models
• Putting it all Together
• A Short Demo
Confidential Information | December 18, 2012 1

3. 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
Confidential Information | December 18, 2012 2

4. 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)
Confidential Information | December 18, 2012 3

5. Resources Have Unique Identifiers (e.g. URIs)
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>!
...!
!
• 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)
Confidential Information | December 18, 2012 4

6. Manipulation of Representations
< 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>!
• Representations (including metadata) contain enough
information to be modified or deleted
• Provided that the client has permission to do so
Confidential Information | December 18, 2012 5

7. Self-descriptive Messages
< 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!
• 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
Confidential Information | December 18, 2012 6

8. Hypermedia as the Engines of Application State
<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
• 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 7

9. REST vs Other Protocols
REST SNMP NETCONF SOAP
Data models SNMP MIBs YANG
Models
Data SMI YANG WSDL
Modeling
Language
Management HTTP Verbs SNMP NETCONF N/A
Operations Operations Operations
RPC Protocol HTTP/XML/ BER XML XML
Encoding JSON
Transport SSL/HTTP/ UDP SSH/TCP SSL/HTTP/
Stack TCP TCP
Confidential Information | December 18, 2012 8

10. 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
Confidential Information | December 18, 2012 9

11. Information Models and Data Models
• Information Models are conceptual, implementation
independent
• Data Models are detailed, intended for implementations
Information Examples: UML, Entity
Model Relations (ER)
Examples: SMI, WSDL,
Data Model Data Model Data Model YANG
Recommended reading: RFC 3444 On the difference between Information
Models and Data Models
Confidential Information | December 18, 2012 10

12. 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
Confidential Information | December 18, 2012 11

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

14. Example Data Model in YANG
interfaces
• We’ll be looking at
– ietf-interface.yang!
interface – ietf-ip.yang!
key: name
• Developed in the IETF
statistics NETMOD WG
ipv4 • More models in the
address
address
making
ipv6
address
address
Confidential Information | December 18, 2012 13

15. 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
Confidential Information | December 18, 2012 14

16. An Example Query (An Ethernet Interface)
1
> 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!
2
< 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>! 3
<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>!
!
Confidential Information | December 18, 2012 15

17. Introducing ConfD and it's REST Interface
REST
NETCONF NETCONF SNMP Web UI
ConfD Core Engine
• Transactions
• AAA/User Sessions
• Logs and audit trails
YANG
Module CDB
Managed Objects API
Managed Managed
Object Object Managed
Managed Object
Object
Confidential Information | December 18, 2012 16

18. 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
Confidential Information | December 18, 2012 17

19. 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
Confidential Information | December 18, 2012 18

20. REST Resources (Datastores)
• Datastores application/vnd.yang.datastore
– running - The running configuration of the device
– startup - The startup configuration of the device
Confidential Information | December 18, 2012 19

21. 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
Confidential Information | December 18, 2012 20

22. (Finally) Time for Demo
• Queries
– Top-level
– Datastores
– Operations
• Interface configuration
– Look at interfaces
– Change IP address
Confidential Information | December 18, 2012 21

23. 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
Confidential Information | December 18, 2012 22

24. 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
– calle@tail-f.com
Confidential Information | December 18, 2012 23