SDNRG L. Li
Internet Draft Z. Wei
Intended status: Informational M. Luo
Expires: December 2016 W. Chou
Huawei Technologies co. ltd
July 8, 2016
Requirements and Design Patterns for REST Northbound API in SDN
draft-li-sdnrg-design-restapi-02.txt
Status of this Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. This document may not be modified,
and derivative works of it may not be created, and it may not be
published except as an Internet-Draft.
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. This document may not be modified,
and derivative works of it may not be created, except to publish it
as an RFC and to translate it into languages other than English.
This document may contain material from IETF Documents or IETF
Contributions published or made publicly available before November
10, 2008. The person(s) controlling the copyright in some of this
material may not have granted the IETF Trust the right to allow
modifications of such material outside the IETF Standards Process.
Without obtaining an adequate license from the person(s) controlling
the copyright in such materials, this document may not be modified
outside the IETF Standards Process, and derivative works of it may
not be created outside the IETF Standards Process, except to format
it for publication as an RFC or to translate it into languages other
than English.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet-
Drafts.
Internet-Drafts are draft documents valid for a maximum of six
months and may be updated, replaced, or obsoleted by other documents
at any time. It is inappropriate to use Internet-Drafts as
reference material or to cite them other than as "work in progress."
Li, et al. Expires December 8, 2016 [Page 1]
Internet-Draft RESTful Northbound API in SDN July 2016
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html
This Internet-Draft will expire on January 8, 2009.
Copyright Notice
Copyright (c) 2016 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with
respect to this document. Code Components extracted from this
document must include Simplified BSD License text as described in
Section 4.e of the Trust Legal Provisions and are provided without
warranty as described in the Simplified BSD License.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with
respect to this document.
Abstract
As stated in ONF SDN Architecture WG Charter [Arc2013], in the SDN
architecture, the control and data planes are decoupled, network
intelligence and state are logically centralized, and the underlying
network infrastructure is abstracted from the applications. As a
result, network operators gain programmability, automation, and
network control, enabling them to build highly scalable, flexible
networks that readily adapt to changing business needs. In this
architecture, the Northbound API provides interfaces to the external
components where applicable.
As REST architectural style has gained more popularity in
implementing loosely-coupled systems, RESTful services are becoming
the style of choice for SDN Northbound API and gaining increasingly
Li, et al. Expires December 8, 2016 [Page 2]
Internet-Draft RESTful Northbound API in SDN July 2016
importance in SDN architecture, for example, the Floodlight
[Floodlight] has a Northbound API based on REST.
However, despite the recent advances made on RESTful web services,
there is a lack of guidelines for designing RESTful networking
protocols and communication web services, especially based on the
Resource-Oriented Architecture (ROA) that further refines the REST
principles. Many networking protocols that claim to be REST APIs are
not hypertext driven as prescribed by REST. This situation can lead
to REST networking APIs that are not as scalable, extensible,
maintainable, and interoperable as promised by REST.
This document describes the key rules and design patterns for the
SDN Northbound API in a truly RESTful manner, based on our
experiences with REST API designs in general and SDN Northbound API
design in particular. The rules and the design patterns illustrate
the solutions to the common API problems in REST API designs, using
the network virtualization API of OpenStack as an example.
Table of Contents
1. Introduction...................................................4
1.1. Problem Statement.........................................4
2. Conventions used in this document..............................6
2.1. REST API Design Approaches................................7
2.2. REST API Design Rules.....................................8
3. The Design Patterns...........................................11
3.1. Content Negotiation......................................11
3.2. Hyperlink-Driven.........................................12
3.3. URI Pattern..............................................13
3.3.1. Entry URI...........................................13
3.4. Navigation Pattern.......................................14
3.5. Redirection Pattern......................................15
3.6. Filter and Search Patterns...............................16
3.7. Factory and Update Pattern...............................17
3.7.1. Factory Pattern.....................................18
3.7.2. Update Pattern......................................19
4. Cache Pattern.................................................21
5. Security Considerations.......................................21
6. IANA Considerations...........................................21
7. Conclusions...................................................21
8. References....................................................21
8.1. Normative References.....................................21
8.2. Informative References...................................22
Li, et al. Expires December 8, 2016 [Page 3]
Internet-Draft RESTful Northbound API in SDN July 2016
1. Introduction
1.1. Problem Statement
Software-Defined Networking (SDN) decouples the data and control
planes, in which a logically centralized controller controls the
network behaviors based on global network information across various
networking elements. As shown in Figure 1, at the center of SDN is
an SDN controller, which controls the behaviors of underlying data
forwarding elements through some southbound APIs, e.g. OpenFlow
[OpenFlow]. On the other hand, the controller, either implemented in
a centralized or distributed manner, also provides an abstraction of
the network functions with a programmable interface for applications
to consume the network services and configure the network
dynamically. This interface is called the northbound API of SDN.
+--------+ +--------+ +--------+
| APP1 | | APP2 | ... | APPN |
+--------+ +--------+ +--------+
| | |
+-----------------+-----------------+
|
| Northbound API
+---------------------Y-----------------------+
| SDN Controller |
+---------------------------------------------+
|
| Southbound API
+---------------------Y-----------------------+
| Forwarding devices |
+---------------------------------------------+
Figure 1 The architecture of Software-Defined Network (SDN).
In SDN, the data plane and the control plane are typically connected
by a closed control loop:
o The control plane receives network events from the data plane.
o The control plane (the SDN controller and applications) computes
some network operations based on the events for the data plane.
Li, et al. Expires December 8, 2016 [Page 4]
Internet-Draft RESTful Northbound API in SDN July 2016
o The data plane executes the operations which can change the
network states, e.g. data path, etc.
The role of SDN northbound API is to provide a high-level API
between the controller and the applications to facilitate step 2 in
the control loop.
REST is an architecture style for designing networked applications.
As REST architectural style has gained more popularity in
implementing loosely-coupled systems, RESTful services are becoming
the style of choice for northbound API and gaining increasingly
importance in SDN architecture. Adopting REST for the SDN northbound
API within this control architecture has the following benefits:
1. Decentralized management of dynamic resources: a REST system does
not use any centralized resource registry but relies on
connections between resources to discover and manage them as a
whole. REST allows network elements, such as routers, switches,
middle boxes (e.g. NAT and DPI devices), to be independently and
dynamically deployed and changed in a distributed fashion.
2. Heterogeneous technologies: because REST separates resource
representation, identification, and interaction, a REST system
can mix different technologies dynamically to optimize API
performance based on client types, network conditions, and
resource states.
3. Service composition: the current trend in SDN is to use
programming composition to achieve functional flexibility, such
as Click [Click] for data plane compositions and Pyretic
[Pyretic] for control plane compositions. REST can provide
service-oriented compositions that are independent of programming
languages and hardware platforms.
4. Localized migration: since the functions of SDN are fast
evolving, the Northbound APIs of SDN controllers will likely to
change accordingly. REST API supports backward-compatible service
migration through localized migration by which a newly added
resource only affects the resources that connect to it. Combined
with uniform interface and hypertext-driven service discovery, it
can ease the tension between the new service deployments and
backward compatibility.
Li, et al. Expires December 8, 2016 [Page 5]
Internet-Draft RESTful Northbound API in SDN July 2016
5. Scalability: REST achieves scalability by keeping the resource
servers stateless and improves end-to-end performance through
layered caches. This feature will become useful, when an SDN
controller needs to support a large number of concurrent host-
based applications and to use network resources in an efficient
way.
To realize these benefits and advantages of REST, a set of REST
constraints need to be maintained in designing a RESTful API. One of
the grounding principles of REST is "hypertext as the engine of
application state" [Fielding2000], which requires a REST API be
driven by nothing but hypertext. This constraint is often ignored by
some REST API designs which specify the API as a set of fixed
resource URIs through some out-of-band mechanisms, e.g. define them
in an API documentation. Although fixed interfaces design appears to
be easy for clients to use, the fixed resource names, types, and
hierarchies makes the system less flexible as it violate the REST
design principles prescribed by Roy Fielding [Fielding2008]. Another
common mistake is to overload HTTP GET to perform arbitrary actions,
e.g. update, on resources. Such mistake can corrupt a REST System as
it fools the caches and misuses idempotent and safe operations.
Violations of REST design principles result in APIs that may not be
as scalable, extensible, and interoperable as promised by REST.
To avoid such violations, this document summarizes the key REST API
design rules and pattern, with some concrete API examples.
2. Conventions used in this document
In examples, "C:" and "S:" indicate lines sent by the client and
server respectively.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC-2119 [RFC2119].
In this document, these words will appear with that interpretation
only when in ALL CAPS. Lower case uses of these words are not to be
interpreted as carrying RFC-2119 significance.
In this document, the characters ">>" preceding an indented line(s)
indicates a compliance requirement statement using the key words
listed above. This convention aids reviewers in quickly identifying
or finding the explicit compliance requirements of this RFC.
Li, et al. Expires December 8, 2016 [Page 6]
Internet-Draft RESTful Northbound API in SDN July 2016
2.1. REST API Design Approaches
Broadly speaking, a REST API can be designed top-down or bottom up.
In a top-down design, the REST API is designed and maintained by a
central organization, whereas in a bottom-up design, the REST API is
designed and maintained by independent but collaborative
organizations. Top-down design exercises central control and is
generally suitable for a stable REST API whose resource model
evolves slowly over time. Bottom-up design forfeits central control
and is suitable for a dynamic REST API whose resource model can
change rapidly.
YANG [37] is an example of top-down design. YANG from IETF is a
hierarchical data modeling language that describes the structure,
operations, and contents of data stores on network devices to be
configured by remote clients through RPC or HTTP protocols. A YANG
model consists of modules, and a module is made up by statements, in
which the data statements define the structure of a data store in
terms of primitive types, and the operation statements define the
operations (query, create, delete, insert, merge, modify, etc.) in
terms of input and output messages. YANG also includes a set of
advanced features such as conditional extensions and data
constraints, which can be used in combination to create complex and
dynamic relations in data models. YANG can be mapped to XML syntax
called YIN [37].
Based on the YANG modeling language, RESTCONF [38] from IETF
specifies a HTTP protocol to access the data stores on network
devices, as a compatible alternative to the NETCONF RPC protocol
[50]. To access a data store, a client first discovers the entry URI
to the RESTCONF API from the predefined URI on the device. From the
entry URI, the client can retrieve the entire data store, which is
essentially a tree with different types of nodes, as well as the
YANG modules that describe the data store. The client can determine
the URI to any node in the data store by combining the entry URI
with the relative path to the node and the HTTP operations on the
node according to the YANG modules and the capabilities of the data
store, which can be discovered by the client. RESTCONF is included
in OpenDaylight [39], an open source SDN Controller platform.
RESTCONF adopts a top-down design where the resource model (resource
types and relationships) of a data store is predefined and made
available to the clients as YANG modules. Exposing all the resource
connections of a data store to a client is necessary in this case
because modifying a node in the data store may affect its children.
Using a path, instead of a hyperlink, to identify a node in the data
store, is efficient if resource identifications and connections do
Li, et al. Expires December 8, 2016 [Page 7]
Internet-Draft RESTful Northbound API in SDN July 2016
not evolve independently. For example, moving a <container> node to
a different path always creates a new <container> resource and
therefore a new URI.
The Web is a good example of bottom-up design that can accommodate
rapid and large scale changes without a central authority. A network
is a complex distributed system whose structure, function, resource,
and behavior can change dynamically, as more elements of the network
are virtualized by software. As virtualized network devices and
functions (e.g. switches, routers, NAT, FW and ID, etc.) can be
connected and disconnected in almost any order in seconds, it is
difficult and unnecessary for a REST API to fix a resource model for
the clients.
To cope with such rapid changes without frequent updates to the
clients, a bottom-up design of REST API is more effective, where a
client can interact with a resource without knowing all its
connections. To follow this design, a REST API only fixes the
hypertext formats at design time, and the clients can use hypertext-
driven navigation to discover the resource identifications and
connections at runtime.
2.2. REST API Design Rules
Roy Fielding explains how REST API should be driven by hypermedia
(hypermedia constraint) with 6 rules as quoted below [Fielding2008],
(the rules are numbered here for ease of reference):
R1. A REST API should not be dependent on any single communication
protocol, though its successful mapping to a given protocol may be
dependent on the availability of metadata, choice of methods, etc.
In general, any protocol element that uses a URI for identification
must allow any URI scheme to be used for the sake of that
identification. [Failure here implies that identification is not
separated from interaction.]
R2. A REST API should not contain any changes to the communication
protocols aside from filling-out or fixing the details of
underspecified bits of standard protocols, such as HTTP's PATCH
method or Link header field. Workarounds for broken implementations
(such as those browsers stupid enough to believe that HTML defines
HTTP's method set) should be defined separately or at least in
appendices, with an expectation that the workaround will eventually
be obsolete. [Failure here implies that the resource interfaces are
object-specific, not generic.]
Li, et al. Expires December 8, 2016 [Page 8]
Internet-Draft RESTful Northbound API in SDN July 2016
R3. A REST API should spend almost all of its descriptive effort in
defining the media type(s) used for representing resources and
driving application state, or in defining extended relation names
and/or hypertext-enabled mark-up for existing standard media types.
Any effort spent describing what methods to use on what URIs of
interest should be entirely defined within the scope of the
processing rules for a media type (and, in most cases, already
defined by existing media types). [Failure here implies that out-of-
band information is driving interaction instead of hypertext.]
R4. A REST API must not define fixed resource names or hierarchies
(an obvious coupling of client and server). Servers must have the
freedom to control their own namespace. Instead, allow servers to
instruct clients on how to construct appropriate URIs, such as is
done in HTML forms and URI templates, by defining those instructions
within media types and link relations. [Failure here implies that
clients are assuming a resource structure due to out-of band
information, such as a domain-specific standard, which is the data-
oriented equivalent to RPC's functional coupling].
R5. A REST API should never have "typed" resources that are
significant to the client. Specification authors may use resource
types for describing server implementation behind the interface, but
those types must be irrelevant and invisible to the client. The only
types that are significant to a client are the current
representation's media type and standardized relation names. [ditto]
R6. A REST API should be entered with no prior knowledge beyond the
initial URI (bookmark) and set of standardized media types that are
appropriate for the intended audience (i.e., expected to be
understood by any client that might use the API). From that point on,
all application state transitions must be driven by client selection
of server-provided choices that are present in the received
representations or implied by the user's manipulation of those
representations. The transitions may be determined (or limited by)
the client's knowledge of media types and resource communication
mechanisms, both of which may be improved on-the-fly (e.g., code-on-
demand). [Failure here implies that out-of-band information is
driving interaction instead of hypertext.]
Here "hypertext" is used as a synonym for "hypermedia" which refers
to data that combine control information with presentation
information.
Content negotiation is another important part of REST API. HTTP 1.1
supports three types of content negotiations [RFC2616]: 1) server-
driven where the origin server determines the representation for the
Li, et al. Expires December 8, 2016 [Page 9]
Internet-Draft RESTful Northbound API in SDN July 2016
user agent, based on user agent's preferences; 2) agent-driven where
the user agent selects the representation from available ones on the
server; 3) transparent where a cache combines the two types of
content negotiation.
The disadvantages of server-driven negotiation include: 1) the
origin server cannot accurately determine what is best for the user
agent; 2) it requires user agent to send preference on every request;
3) it complicates the implementation of origin servers; 4) it may
limit a public cache's ability to use the same response for multiple
user agents. Agent-driven negotiation avoids these problems but it
requires a second request to retrieve the best representation, which
is inefficient.
An alternative to the above negotiation mechanisms is to express the
available media types in the REST API. This approach enables agent-
driven negotiation without the need for a second request, as the
user agent can select the best representation from the REST API
directly. The disadvantage of this approach is that an origin server
cannot change media types at runtime. But in most cases, the
available media types for a REST API are unlikely to change
frequently. For this reason, we introduce a new rule in addition to
R1-R6 from Fielding [Fielding2008]:
R7. A resource with multiple representations should allow a
representation be selected from the resource [Failure here implies
that identification is not separated from representation].
These rules should be followed by any SDN Northbound API designers,
unless there is a good reason to do otherwise.
In addition to these generic rules, REST API design for SDN should
also facilitate the implementation of CLI (Command-Line Interface)
that has much more flexibility than a GUI. A CLI command typically
consists of four parts:
<interpreter> <object>-<operation> <parameters>
For example, OpenStack [OpenStack] Neutron CLI syntax for deleting a
network gateway is:
neutron net-gateway-delete NET-GATEWAY-ID
where <interpreter> is "neutron," <object> is "net-gateway," and
<operation> is "delete." The CLI interpreter provides a command-
based presentation layer to the user by translating the command into
a REST API request and the hypertext response into line-based output.
Li, et al. Expires December 8, 2016 [Page 10]
Internet-Draft RESTful Northbound API in SDN July 2016
The following REST API design patterns can be easily supported by a
CLI interpreter as these design patterns are independent of the
presentation layers the clients choose to implement over the REST
API. Furthermore, certain design patterns facilitate the
translations between commands and REST API messages. For example,
the URI pattern in 3.3 makes it easy to translate the <object> and
<parameters> parts of a command into the resource URI, while the
factory and update patterns in 3.7 make it easy to translate the
<operation> and <parameter> parts of a command into the proper
request.
The following sections describe some design patterns useful for
designing REST APIs in the SDN domain.
3. The Design Patterns
3.1. Content Negotiation
In a well-designed REST API, the identification (URI),
representation (hypertext), and interaction (e.g. HTTP) should be
orthogonal, such that each of them can evolve and be modified
independently without breaking the API.
Therefore, a media type should not be included in the identification
(URI), because such identification limits the ability for the server
to evolve the representation and identification independently, and
the ability for clients of different capabilities to reuse the same
identification.
Instead, any media type should be removed from the URI, and clients
can use HTTP 1.1 content negotiation mechanism to request different
media types from the same URI. Using the HTTP 1.1 header Accept,
clients can define their preferred media types following [RFC2046].
The following examples show sample HTTP requests that illustrate
clients retrieve the network list information in JSON and XML by
accessing the same URI.
GET /networks HTTP/1.1
Host: localhost:8080
Accept: application/json
GET /networks HTTP/1.1
Host: localhost:8080
Accept: text/xml
Li, et al. Expires December 8, 2016 [Page 11]
Internet-Draft RESTful Northbound API in SDN July 2016
3.2. Hyperlink-Driven
One important REST principle is that the REST API must be hypertext
driven. If resource URIs are predefined by some out-of-band
mechanism, the controller will lose the freedom to change the URIs
when it relocates the resources. Such resource reorganization is
critical, as SDN controllers are expected to evolve and migrate
rapidly to support various applications.
To respect the REST constraint, a REST API should remove any fixed
URI from the REST APIs, except a single entry URI to the API, from
which other URIs are revealed to a client through hypertext-based
interactions between the client and the controller. In this
hypertext-driven approach, the meaning of each URI is defined by the
hypertext in which it occurs and its value can be changed by the
controller without changing its meaning, thus leading to a loosely-
coupled REST architecture.
The common way to assign a meaning to a URI in HTML/XML is to use
the rel attribute of link element. The following examples illustrate
this mechanism by showing the sample HTTP request and responses.
Here we assume the URI template to a network is /networks/{net-id},
which was obtained from the entry URI.
HTTP Request to retrieve a XML or JSON representation of a network
resource:
GET /networks/net1 HTTP/1.1
Host: localhost:8080
Accept: text/xml, application/json
HTTP Response that contains a XML representation of the network
resource with links to the connected ports and subnets resources:
HTTP/1.1 200 OK
Content-Type: text/xml
<network>
<link rel="ports" href="/networks/net1/ports"/>
<link rel="subnets" href="/networks/net1/subnets"/>
</network>
Li, et al. Expires December 8, 2016 [Page 12]
Internet-Draft RESTful Northbound API in SDN July 2016
HTTP Response that contains a JSON representation of the network
resource with the same links in JSON format:
HTTP/1.1 200 OK
Content-Type: application/json
{
"network": {
"links": [
{"rel":"ports",
"href":"/networks/net1/ports"},
{"rel":"subnets",
"href":"/networks/net1/subnets"}
]
}
}
The rel attribute can be absolute URI as well. The values of these
attributes will be defined by a REST API and cannot be changed by
different implementations of the API. Based on these attributes and
the hypertext structure, a client can select the correct resource
URI to follow and at the same time allow the controller to change
the resource URI.
3.3. URI Pattern
The design of URI namespace must allow the server to change current
resource organization and add new resources in a consistent way. For
this purpose, we propose to use design pattern "type/variable" or
"collection/member" pairs for URI templates, to prefix each variable
by a type, which serves as an extension point of the URI template.
An example is to use types "tenant" and "networks" in one URI to
identify the networks owned by a tenant:
{entry}/tenants/{tid}/networks/{nid}.
3.3.1. Entry URI
The entry URI is the absolute URI to a REST API implementation, e.g.
http://www.huawei.com/neutron. By following the definition of this
URI scheme through HTTP, the client can dereference this URI with a
HTTP GET. The response will return the hyperlinks for accessing the
entities supported by this implementation.
Li, et al. Expires December 8, 2016 [Page 13]
Internet-Draft RESTful Northbound API in SDN July 2016
If an API has more than one version, the entry URI could identify a
specific version of the REST API, e.g.
http://www.huawei.com/neutron/v2.0. The server can also use a
generic API, like http://www.huawei.com/neutron, to point to the
latest version, or redirect the clients to the appropriate version
based on their credential or capability.
3.4. Navigation Pattern
The most basic interaction with a REST API is to navigate from an
entry URI to a desired resource to obtain its current representation.
In this framework, the navigation is performed by following a series
of hyperlinks contained in the response.
The following XML Schema shows an example for accessing the network
entity. The returned network_list representation contains a list of
network hyperlinks by which clients can access a specific network.
<schema media_type="application/relax-ng-compact-syntax">
element networks {
...
element link {
attribute rel {"network"}
attribute id {text}
attribute href {xs:anyURI}
}*
element link {
attribute rel {"add"}
attribute id {text}
attribute href {xs:anyURI}
}
element link {
attribute rel {"search"}
attribute id {text}
attribute href {xs:anyURI}
}
}
</schema>
The following example shows the HTTP request and responses for the
network_list representation, where the links consist of relative
URIs.
Li, et al. Expires December 8, 2016 [Page 14]
Internet-Draft RESTful Northbound API in SDN July 2016
HTTP request to retrieve the representation of a collection of
networks:
GET /networks HTTP/1.1
Host: localhost:8080
Accept: text/xml, application/json
HTTP response that contains a XML representation with a list of
links to the network in the collection:
HTTP/1.1 200 OK
Content-Type: text/xml
<networks>
<link rel="network" href="/networks/net1" />
<link rel="network" href="/networks/net2"/>
<link rel="network" href="/networks/net3"/>
<link rel="add" href="/networks/factory" />
<link rel="search"
href="/networks/search?{key1}={value1}&...&{keyN}={valueN}" />
</networks>
3.5. Redirection Pattern
HTTP 1.1 redirection [RFC2616] can be used to inform a client the
existence of new service and/or new location of a resource. For
example, the following request-response interaction allows a client
to learn the new location of the update service:
HTTP request:
GET /networks/net1/update HTTP/1.1
Host: localhost:8080
Accept: text/xml, application/json
HTTP response:
HTTP/1.1 301 Moved Permanently
Location: /networks/net1/new_update
One primary advantage of redirection is that a REST API does not
have to change its media types. The disadvantage is that the REST
API cannot delete the redirecting resource (e.g.
Li, et al. Expires December 8, 2016 [Page 15]
Internet-Draft RESTful Northbound API in SDN July 2016
/networks/net1/update) to claim the memory it takes. However, it is
possible to delete the redirecting resources after a certain
transition period, when most clients have learnt the new service and
the redirection is no longer needed.
3.6. Filter and Search Patterns
By default, the representation of the navigation pattern contains
only the hyperlink for each listed entity resource. This can
effectively reduce the representation size, especially when the
number of entities is large. This however may not be efficient for
other use cases. For example, clients may need to retrieve the names
of all entities but not the entire representations. With current
design, this is impossible because the client has to retrieve the
entire network representation to get the name in it.
The filter pattern is designed to address this issue. The pattern
allows client to request additional content using
"?attributes={name1,...,nameN}" URI query string. As shown in the
following, the client requests the name and id elements in addition
to the default content.
HTTP Request:
GET /networks?attributes=name,id HTTP/1.1
Host: localhost:8080
Accept: text/xml, application/json
HTTP Response:
HTTP/1.1 200 OK
Content-Type: text/xml
<networks>
<network>
<name>myNet</name>
<id>net1</id>
<link rel="network" href="/networks/net1" />
</network>
<link rel="add" href="/networks/factory" />
<link rel="search"
href="/networks/search?{key1}={value1}&...&{keyN}={valueN}" />
</networks>
Li, et al. Expires December 8, 2016 [Page 16]
Internet-Draft RESTful Northbound API in SDN July 2016
If a tenant has a large number of entities, it would be very
inefficient for the client to use the navigation pattern to locate a
specific entity. To address this problem, the search pattern is
designed by providing a hyperlink containing a URI template to allow
clients to submit queries consisting of key-value pairs. The
following example shows HTTP request and response for a search
pattern to find all networks that are shared between tenants:
HTTP Request with a search parameter shared=true:
GET /networks/search?shared=true HTTP/1.1
Host: localhost:8080
Accept: text/xml, application/json
HTTP Response that contains links to two network resources (i.e.
net1 and net2) that are shared:
HTTP/1.1 200 OK
Content-Type: text/xml
<networks>
<link rel="network" href="/networks/net1" />
<link rel="network" href="/networks/net2" />
</networks>
3.7. Factory and Update Pattern
When creating or updating a resource, clients may have to deal with
the special constraints on the resource attributes: some of the
attributes are required in creating a resource, while some
attributes are read only and cannot be updated.
These constraints of attributes are usually implicit, where
programmers have to check the documents to identify these
constraints. This is inefficient and error prone. Furthermore, the
server may change these rules in the future, which could compromise
the clients.
To address the issue, the framework here applies an explicit
approach of enforcing these constraints. Rather than presenting the
constraints in documents, we apply a form-based approach to enforce
these constraints at runtime.
Li, et al. Expires December 8, 2016 [Page 17]
Internet-Draft RESTful Northbound API in SDN July 2016
3.7.1. Factory Pattern
The factory pattern returns a form to the client claiming the
constraints on the attributes. In the form, all the required
attributes are marked required=true. The form also provides default
values for some unmarked attributes. This allows clients to be
programmed adaptively to cope with these explicit constraints. In
particular, the attribute method of the form element indicates that
the client should submit the filled-out form by the HTTP command
POST.
This form can be defined as follows using RELAX-NG XML Schema:
<schema media_type="application/relax-ng-compact-syntax">
element form {
attribute method {"POST"}
element network {
element id {
attribute required {"true"} text
}
element name { text }
element admin { text }
element shared { text }
element tenant { attribute required {"false"} }
}
element link {
attribute rel {"target"}
attribute id {text}
attribute href {xs:anyURI}
}?
}
</schema>
The following shows such an example form of factory pattern about
creating a new virtual network. Here we assume that the URI for
creating a new virtual network is /networks/factory. By default, an
attribute is marked as required=false.
HTTP Request to retrieve a representation of the factory resource:
GET /networks/factory HTTP/1.1
Host: localhost:8080
Accept: text/xml, application/json
Li, et al. Expires December 8, 2016 [Page 18]
Internet-Draft RESTful Northbound API in SDN July 2016
HTTP Response that contains an empty XML form for the client to fill
and submit to the target resource in order to create a network:
HTTP/1.1 200 OK
Content-Type: text/xml
<form method="POST">
<network>
<id required="true" />
<name />
<admin>true</admin>
<shared>true</shared>
<tenant_required="true" />
</network>
<link rel="target" href="/networks/factory">
</form>
The resource created by one factory can be another factory, to form
a factory chain. The organization of the chain is not static but
determined by the hypertext from a REST API at runtime.
3.7.2. Update Pattern
Similar to the factory pattern, the update pattern also returns a
form to the client showing explicit rules of updates. In this case,
the attributes which are allowed to be updated are included in the
form, while the missing attributes are read only. In addition, the
method is now PUT to comply with the REST constraint of uniform
interface.
This form can be defined as follows using RELAX-NG XML Schema:
Li, et al. Expires December 8, 2016 [Page 19]
Internet-Draft RESTful Northbound API in SDN July 2016
<schema media_type="application/relax-ng-compact-syntax">
element form {
attribute method {"PUT"}
element network {
element name { text }
element admin { text }
element shared { text }
}
element link {
attribute rel {"target"}
attribute id {text}
attribute href {xs:anyURI}
}?
}
</schema>
The following shows such an example form of the update pattern about
updating an existed virtual network. Here we assume the ID of the
virtual network is net1 and the corresponding URI is
/networks/net1/update.
HTTP Request to retrieve a representation of the network modifier
resource:
GET /networks/net1/update HTTP/1.1
Host: localhost:8080
Accept: text/xml, application/json
HTTP Response that contains a pre-filled XML form for the client to
change and submit to the target resource in order to update the
network:
HTTP/1.1 200 OK
Content-Type: text/xml
<form method="PUT">
<network>
<name>myNet1</name>
<admin_state_up>true</admin_state_up>
<shared>true</shared>
</network>
<link rel="target" href="/networks/net1/update">
</form>
Li, et al. Expires December 8, 2016 [Page 20]
Internet-Draft RESTful Northbound API in SDN July 2016
4. Cache Pattern
Clients accessing the hypertext-driven REST API for the first time
should start from the entry URI and follow the returned hyperlinks
to access other resources. This provides the REST API with desired
flexibility and extensibility including the loosely-coupled and late
binding features. After the first visit, the client and intermediary
proxies should be able to cache the returned representations
according to HTTP 1.1. Cache Control [RFC2616] to reduce network
traffic for future interactions with the server. An efficient
approach to cache in Northbound API of SDN is described in
[Zhou2014a] and [Zhou2014b].
5. Security Considerations
<Add any security considerations>
6. IANA Considerations
<Add any IANA considerations>
7. Conclusions
This document summarizes the REST rules and design patterns for SDN
Northbound API, using OpenStack Northbound virtual network
management API as an example. With these rules and patterns, it will
lead to a REST API that is scalable, extensible, and interoperable
as the true RESTful approach promises. In addition, it avoids some
common mistakes in REST API designs, and it can achieve desired
quality and consistency in SDN Northbound API designs.
8. References
8.1. Normative References
[RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
Extensions (MIME) Part Two: Media Types", RFC 2046,
November 1996.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2234] Crocker, D. and Overell, P.(Editors), "Augmented BNF for
Syntax Specifications: ABNF", RFC 2234, Internet Mail
Consortium and Demon Internet Ltd., November 1997.
Li, et al. Expires December 8, 2016 [Page 21]
Internet-Draft RESTful Northbound API in SDN July 2016
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter,
L., Leach, P., and T. Berners-Lee, "Hypertext Transfer
Protocol -- HTTP/1.1", RFC 2616, June 1999.
8.2. Informative References
[SDN-Arch]
https://www.opennetworking.org/images/stories/downloads/wo
rking-groups/charter-architecture-framework.pdf
[Cassandras2008] C. G. Cassandras, et al, Introduction to Discrete
Event Systems, second edition, Chpater 4, Springer, 2008.
[Click] Click, <http://www.read.cs.ucla.edu/click/click>.
[Fielding2000] R. T. Fielding, Architectural styles and the design
of network-based software architectures, Ph.D.
Dissertation, University of California, Irvine, 2000,
<http://www.ics.uci.edu/~fielding/pubs/dissertation/top.ht
m>.
[Fielding2008] R. T. Fielding, "REST API must be hypertext driven,"
28 October, 2008,
<http://roy.gbiv.com/untangled/2008/rest-apis-must-be-
hypertext-driven>.
[Floodlight] http://www.projectfloodlight.org/floodlight/.
[Jensen1997] K. Jensen, Coloured Petri Nets, Springer Verlag, 1997.
[Li2011] L. Li and W. Chou, Design and describe REST API without
violating REST: a Petri net based approach, Proceedings of
the 2011 IEEE International Conference on Web Services,
508-515, 2011.
[OpenFlow] Open Networking Foundation, "The OpenFlow 1.4.0
Specification.",
<https://www.opennetworking.org/images/stories/downloads/s
dn-resources/onf-specifications/openflow/openflow-spec-
v1.3.0.pdf>.
[OpenStack] OpenStack Foundation. OpenStack networking
administration guide, Feb 2013,
http://docs.openstack.org/trunk/openstack-network/
admin/content/index.html.
[Pyretic] Pyretic, <http://frenetic-lang.org/pyretic/>.
Li, et al. Expires December 8, 2016 [Page 22]
Internet-Draft RESTful Northbound API in SDN July 2016
[Richardson2007] Leonard Richardson, Sam Ruby, Restful Web Services,
O'Reilly, 2007.
[Zhou2014a] Wei Zhou, Li Li, Min Luo, Wu Chou: REST API Design
Patterns for SDN Northbound API, The 28th IEEE
International Conference on Advanced Information
Networking and Applications Workshops (AINA-2014), pages
358-365, Victoria, BC, Canada, May 13-16, 2014.
[Zhou2014b] Wei Zhou, Li Li, Wu Chou: SDN Northbound REST API with
Efficient Caches, to appear in ICWS2014, Anchorage, Alaska,
June 26-July 2, 2014.
Authors' Addresses
Wei Zhou
Huawei Technologies co. ltd.
Email: sky.zhouwei@huawei.com
Li Li
Huawei Technologies co. ltd.
Email: li.nj.li@huawei.com
Min Luo
Huawei Technologies co. ltd.
Email: min.ch.luo@huawei.com
Wu Chou
Huawei Technologies co. ltd.
Email: wu.chou@huawei.com
Li, et al. Expires December 8, 2016 [Page 23]