SDNRG L. Li
Internet Draft Z. Wei
Intended status: Informational M. Luo
Expires: September 2016 W. Chou
Huawei Technologies co. ltd
March 14, 2016
Requirements and Design Patterns for REST Northbound API in SDN
draft-li-sdnrg-design-restapi-01.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 September 14, 2016 [Page 1]
Internet-Draft RESTful Northbound API in SDN March 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 September 14, 2015.
Copyright Notice
Copyright (c) 2015 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 September 14, 2016 [Page 2]
Internet-Draft RESTful Northbound API in SDN March 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 Design Rules.........................................7
3. The Design Patterns............................................9
3.1. Content Negotiation.......................................9
3.2. Hyperlink-Driven.........................................10
3.3. URI Pattern..............................................11
3.3.1. Entry URI...........................................11
3.4. Navigation Pattern.......................................12
3.5. Filter and Search Patterns...............................13
3.6. Factory and Update Pattern...............................15
3.6.1. Factory Pattern.....................................15
3.6.2. Update Pattern......................................17
4. Cache.........................................................18
5. Security Considerations.......................................19
6. IANA Considerations...........................................19
7. Conclusions...................................................19
8. References....................................................19
8.1. Normative References.....................................19
8.2. Informative References...................................19
Li, et al. Expires September 14, 2016 [Page 3]
Internet-Draft RESTful Northbound API in SDN March 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 September 14, 2016 [Page 4]
Internet-Draft RESTful Northbound API in SDN March 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 September 14, 2016 [Page 5]
Internet-Draft RESTful Northbound API in SDN March 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 September 14, 2016 [Page 6]
Internet-Draft RESTful Northbound API in SDN March 2016
2.1. REST 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.]
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
Li, et al. Expires September 14, 2016 [Page 7]
Internet-Draft RESTful Northbound API in SDN March 2016
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
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]:
Li, et al. Expires September 14, 2016 [Page 8]
Internet-Draft RESTful Northbound API in SDN March 2016
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. To facilitate the
adoption of these rules, we describe in the following section some
design patterns to common API design problems.
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 September 14, 2016 [Page 9]
Internet-Draft RESTful Northbound API in SDN March 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