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 node to a different path always creates a new 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: - For example, OpenStack [OpenStack] Neutron CLI syntax for deleting a network gateway is: neutron net-gateway-delete NET-GATEWAY-ID where is "neutron," is "net-gateway," and 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 and parts of a command into the resource URI, while the factory and update patterns in 3.7 make it easy to translate the and 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 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. 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} } } 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 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 myNet net1 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 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: 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} }? } 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
true true
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 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} }? } 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
myNet1 true true
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 6. 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, . [Fielding2000] R. T. Fielding, Architectural styles and the design of network-based software architectures, Ph.D. Dissertation, University of California, Irvine, 2000, . [Fielding2008] R. T. Fielding, "REST API must be hypertext driven," 28 October, 2008, . [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.", . [OpenStack] OpenStack Foundation. OpenStack networking administration guide, Feb 2013, http://docs.openstack.org/trunk/openstack-network/ admin/content/index.html. [Pyretic] 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]