[Search] [pdf|bibtex] [Tracker] [Email] [Diff1] [Diff2] [Nits]

Versions: 00 01 02                                                      
     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]