idnits 2.17.1 draft-li-sdnrg-design-restapi-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- -- The document has an IETF Trust Provisions (28 Dec 2009) Section 6.c(ii) Publication Limitation clause. If this document is intended for submission to the IESG for publication, this constitutes an error. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == The page length should not exceed 58 lines per page, but there was 23 longer pages, the longest (page 1) being 61 lines == It seems as if not all pages are separated by form feeds - found 0 form feeds but 23 pages Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 305 instances of too long lines in the document, the longest one being 5 characters in excess of 72. ** The abstract seems to contain references ([Arc2013], [Floodlight]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document doesn't use any RFC 2119 keywords, yet seems to have RFC 2119 boilerplate text. == The document seems to contain a disclaimer for pre-RFC5378 work, but was first submitted on or after 10 November 2008. The disclaimer is usually necessary only for documents that revise or obsolete older RFCs, and that take significant amounts of text from those RFCs. If you can contact all authors of the source material and they are willing to grant the BCP78 rights to the IETF Trust, you can and should remove the disclaimer. Otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (July 8, 2016) is 2848 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'Arc2013' is mentioned on line 80, but not defined -- Looks like a reference, but probably isn't: '37' on line 292 -- Looks like a reference, but probably isn't: '38' on line 294 -- Looks like a reference, but probably isn't: '50' on line 297 -- Looks like a reference, but probably isn't: '39' on line 306 == Unused Reference: 'RFC2234' is defined on line 920, but no explicit reference was found in the text == Unused Reference: 'SDN-Arch' is defined on line 930, but no explicit reference was found in the text == Unused Reference: 'Cassandras2008' is defined on line 934, but no explicit reference was found in the text == Unused Reference: 'Jensen1997' is defined on line 952, but no explicit reference was found in the text == Unused Reference: 'Li2011' is defined on line 954, but no explicit reference was found in the text == Unused Reference: 'Richardson2007' is defined on line 972, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2234 (Obsoleted by RFC 4234) ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) Summary: 4 errors (**), 0 flaws (~~), 12 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 SDNRG L. Li 3 Internet Draft Z. Wei 4 Intended status: Informational M. Luo 5 Expires: December 2016 W. Chou 6 Huawei Technologies co. ltd 7 July 8, 2016 9 Requirements and Design Patterns for REST Northbound API in SDN 10 draft-li-sdnrg-design-restapi-02.txt 12 Status of this Memo 14 This Internet-Draft is submitted in full conformance with the 15 provisions of BCP 78 and BCP 79. 17 This Internet-Draft is submitted in full conformance with the 18 provisions of BCP 78 and BCP 79. This document may not be modified, 19 and derivative works of it may not be created, and it may not be 20 published except as an Internet-Draft. 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. This document may not be modified, 24 and derivative works of it may not be created, except to publish it 25 as an RFC and to translate it into languages other than English. 27 This document may contain material from IETF Documents or IETF 28 Contributions published or made publicly available before November 29 10, 2008. The person(s) controlling the copyright in some of this 30 material may not have granted the IETF Trust the right to allow 31 modifications of such material outside the IETF Standards Process. 32 Without obtaining an adequate license from the person(s) controlling 33 the copyright in such materials, this document may not be modified 34 outside the IETF Standards Process, and derivative works of it may 35 not be created outside the IETF Standards Process, except to format 36 it for publication as an RFC or to translate it into languages other 37 than English. 39 Internet-Drafts are working documents of the Internet Engineering 40 Task Force (IETF), its areas, and its working groups. Note that 41 other groups may also distribute working documents as Internet- 42 Drafts. 44 Internet-Drafts are draft documents valid for a maximum of six 45 months and may be updated, replaced, or obsoleted by other documents 46 at any time. It is inappropriate to use Internet-Drafts as 47 reference material or to cite them other than as "work in progress." 48 The list of current Internet-Drafts can be accessed at 49 http://www.ietf.org/ietf/1id-abstracts.txt 51 The list of Internet-Draft Shadow Directories can be accessed at 52 http://www.ietf.org/shadow.html 54 This Internet-Draft will expire on January 8, 2009. 56 Copyright Notice 58 Copyright (c) 2016 IETF Trust and the persons identified as the 59 document authors. All rights reserved. 61 This document is subject to BCP 78 and the IETF Trust's Legal 62 Provisions Relating to IETF Documents 63 (http://trustee.ietf.org/license-info) in effect on the date of 64 publication of this document. Please review these documents 65 carefully, as they describe your rights and restrictions with 66 respect to this document. Code Components extracted from this 67 document must include Simplified BSD License text as described in 68 Section 4.e of the Trust Legal Provisions and are provided without 69 warranty as described in the Simplified BSD License. 71 This document is subject to BCP 78 and the IETF Trust's Legal 72 Provisions Relating to IETF Documents 73 (http://trustee.ietf.org/license-info) in effect on the date of 74 publication of this document. Please review these documents 75 carefully, as they describe your rights and restrictions with 76 respect to this document. 78 Abstract 80 As stated in ONF SDN Architecture WG Charter [Arc2013], in the SDN 81 architecture, the control and data planes are decoupled, network 82 intelligence and state are logically centralized, and the underlying 83 network infrastructure is abstracted from the applications. As a 84 result, network operators gain programmability, automation, and 85 network control, enabling them to build highly scalable, flexible 86 networks that readily adapt to changing business needs. In this 87 architecture, the Northbound API provides interfaces to the external 88 components where applicable. 90 As REST architectural style has gained more popularity in 91 implementing loosely-coupled systems, RESTful services are becoming 92 the style of choice for SDN Northbound API and gaining increasingly 93 importance in SDN architecture, for example, the Floodlight 94 [Floodlight] has a Northbound API based on REST. 96 However, despite the recent advances made on RESTful web services, 97 there is a lack of guidelines for designing RESTful networking 98 protocols and communication web services, especially based on the 99 Resource-Oriented Architecture (ROA) that further refines the REST 100 principles. Many networking protocols that claim to be REST APIs are 101 not hypertext driven as prescribed by REST. This situation can lead 102 to REST networking APIs that are not as scalable, extensible, 103 maintainable, and interoperable as promised by REST. 105 This document describes the key rules and design patterns for the 106 SDN Northbound API in a truly RESTful manner, based on our 107 experiences with REST API designs in general and SDN Northbound API 108 design in particular. The rules and the design patterns illustrate 109 the solutions to the common API problems in REST API designs, using 110 the network virtualization API of OpenStack as an example. 112 Table of Contents 114 1. Introduction...................................................4 115 1.1. Problem Statement.........................................4 116 2. Conventions used in this document..............................6 117 2.1. REST API Design Approaches................................7 118 2.2. REST API Design Rules.....................................8 119 3. The Design Patterns...........................................11 120 3.1. Content Negotiation......................................11 121 3.2. Hyperlink-Driven.........................................12 122 3.3. URI Pattern..............................................13 123 3.3.1. Entry URI...........................................13 124 3.4. Navigation Pattern.......................................14 125 3.5. Redirection Pattern......................................15 126 3.6. Filter and Search Patterns...............................16 127 3.7. Factory and Update Pattern...............................17 128 3.7.1. Factory Pattern.....................................18 129 3.7.2. Update Pattern......................................19 130 4. Cache Pattern.................................................21 131 5. Security Considerations.......................................21 132 6. IANA Considerations...........................................21 133 7. Conclusions...................................................21 134 8. References....................................................21 135 8.1. Normative References.....................................21 136 8.2. Informative References...................................22 138 1. Introduction 140 1.1. Problem Statement 142 Software-Defined Networking (SDN) decouples the data and control 143 planes, in which a logically centralized controller controls the 144 network behaviors based on global network information across various 145 networking elements. As shown in Figure 1, at the center of SDN is 146 an SDN controller, which controls the behaviors of underlying data 147 forwarding elements through some southbound APIs, e.g. OpenFlow 148 [OpenFlow]. On the other hand, the controller, either implemented in 149 a centralized or distributed manner, also provides an abstraction of 150 the network functions with a programmable interface for applications 151 to consume the network services and configure the network 152 dynamically. This interface is called the northbound API of SDN. 154 +--------+ +--------+ +--------+ 155 | APP1 | | APP2 | ... | APPN | 156 +--------+ +--------+ +--------+ 157 | | | 158 +-----------------+-----------------+ 159 | 160 | Northbound API 161 +---------------------Y-----------------------+ 162 | SDN Controller | 163 +---------------------------------------------+ 164 | 165 | Southbound API 166 +---------------------Y-----------------------+ 167 | Forwarding devices | 168 +---------------------------------------------+ 170 Figure 1 The architecture of Software-Defined Network (SDN). 172 In SDN, the data plane and the control plane are typically connected 173 by a closed control loop: 175 o The control plane receives network events from the data plane. 177 o The control plane (the SDN controller and applications) computes 178 some network operations based on the events for the data plane. 180 o The data plane executes the operations which can change the 181 network states, e.g. data path, etc. 183 The role of SDN northbound API is to provide a high-level API 184 between the controller and the applications to facilitate step 2 in 185 the control loop. 187 REST is an architecture style for designing networked applications. 188 As REST architectural style has gained more popularity in 189 implementing loosely-coupled systems, RESTful services are becoming 190 the style of choice for northbound API and gaining increasingly 191 importance in SDN architecture. Adopting REST for the SDN northbound 192 API within this control architecture has the following benefits: 194 1. Decentralized management of dynamic resources: a REST system does 195 not use any centralized resource registry but relies on 196 connections between resources to discover and manage them as a 197 whole. REST allows network elements, such as routers, switches, 198 middle boxes (e.g. NAT and DPI devices), to be independently and 199 dynamically deployed and changed in a distributed fashion. 201 2. Heterogeneous technologies: because REST separates resource 202 representation, identification, and interaction, a REST system 203 can mix different technologies dynamically to optimize API 204 performance based on client types, network conditions, and 205 resource states. 207 3. Service composition: the current trend in SDN is to use 208 programming composition to achieve functional flexibility, such 209 as Click [Click] for data plane compositions and Pyretic 210 [Pyretic] for control plane compositions. REST can provide 211 service-oriented compositions that are independent of programming 212 languages and hardware platforms. 214 4. Localized migration: since the functions of SDN are fast 215 evolving, the Northbound APIs of SDN controllers will likely to 216 change accordingly. REST API supports backward-compatible service 217 migration through localized migration by which a newly added 218 resource only affects the resources that connect to it. Combined 219 with uniform interface and hypertext-driven service discovery, it 220 can ease the tension between the new service deployments and 221 backward compatibility. 223 5. Scalability: REST achieves scalability by keeping the resource 224 servers stateless and improves end-to-end performance through 225 layered caches. This feature will become useful, when an SDN 226 controller needs to support a large number of concurrent host- 227 based applications and to use network resources in an efficient 228 way. 230 To realize these benefits and advantages of REST, a set of REST 231 constraints need to be maintained in designing a RESTful API. One of 232 the grounding principles of REST is "hypertext as the engine of 233 application state" [Fielding2000], which requires a REST API be 234 driven by nothing but hypertext. This constraint is often ignored by 235 some REST API designs which specify the API as a set of fixed 236 resource URIs through some out-of-band mechanisms, e.g. define them 237 in an API documentation. Although fixed interfaces design appears to 238 be easy for clients to use, the fixed resource names, types, and 239 hierarchies makes the system less flexible as it violate the REST 240 design principles prescribed by Roy Fielding [Fielding2008]. Another 241 common mistake is to overload HTTP GET to perform arbitrary actions, 242 e.g. update, on resources. Such mistake can corrupt a REST System as 243 it fools the caches and misuses idempotent and safe operations. 244 Violations of REST design principles result in APIs that may not be 245 as scalable, extensible, and interoperable as promised by REST. 247 To avoid such violations, this document summarizes the key REST API 248 design rules and pattern, with some concrete API examples. 250 2. Conventions used in this document 252 In examples, "C:" and "S:" indicate lines sent by the client and 253 server respectively. 255 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 256 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 257 document are to be interpreted as described in RFC-2119 [RFC2119]. 259 In this document, these words will appear with that interpretation 260 only when in ALL CAPS. Lower case uses of these words are not to be 261 interpreted as carrying RFC-2119 significance. 263 In this document, the characters ">>" preceding an indented line(s) 264 indicates a compliance requirement statement using the key words 265 listed above. This convention aids reviewers in quickly identifying 266 or finding the explicit compliance requirements of this RFC. 268 2.1. REST API Design Approaches 270 Broadly speaking, a REST API can be designed top-down or bottom up. 271 In a top-down design, the REST API is designed and maintained by a 272 central organization, whereas in a bottom-up design, the REST API is 273 designed and maintained by independent but collaborative 274 organizations. Top-down design exercises central control and is 275 generally suitable for a stable REST API whose resource model 276 evolves slowly over time. Bottom-up design forfeits central control 277 and is suitable for a dynamic REST API whose resource model can 278 change rapidly. 280 YANG [37] is an example of top-down design. YANG from IETF is a 281 hierarchical data modeling language that describes the structure, 282 operations, and contents of data stores on network devices to be 283 configured by remote clients through RPC or HTTP protocols. A YANG 284 model consists of modules, and a module is made up by statements, in 285 which the data statements define the structure of a data store in 286 terms of primitive types, and the operation statements define the 287 operations (query, create, delete, insert, merge, modify, etc.) in 288 terms of input and output messages. YANG also includes a set of 289 advanced features such as conditional extensions and data 290 constraints, which can be used in combination to create complex and 291 dynamic relations in data models. YANG can be mapped to XML syntax 292 called YIN [37]. 294 Based on the YANG modeling language, RESTCONF [38] from IETF 295 specifies a HTTP protocol to access the data stores on network 296 devices, as a compatible alternative to the NETCONF RPC protocol 297 [50]. To access a data store, a client first discovers the entry URI 298 to the RESTCONF API from the predefined URI on the device. From the 299 entry URI, the client can retrieve the entire data store, which is 300 essentially a tree with different types of nodes, as well as the 301 YANG modules that describe the data store. The client can determine 302 the URI to any node in the data store by combining the entry URI 303 with the relative path to the node and the HTTP operations on the 304 node according to the YANG modules and the capabilities of the data 305 store, which can be discovered by the client. RESTCONF is included 306 in OpenDaylight [39], an open source SDN Controller platform. 308 RESTCONF adopts a top-down design where the resource model (resource 309 types and relationships) of a data store is predefined and made 310 available to the clients as YANG modules. Exposing all the resource 311 connections of a data store to a client is necessary in this case 312 because modifying a node in the data store may affect its children. 313 Using a path, instead of a hyperlink, to identify a node in the data 314 store, is efficient if resource identifications and connections do 315 not evolve independently. For example, moving a node to 316 a different path always creates a new resource and 317 therefore a new URI. 319 The Web is a good example of bottom-up design that can accommodate 320 rapid and large scale changes without a central authority. A network 321 is a complex distributed system whose structure, function, resource, 322 and behavior can change dynamically, as more elements of the network 323 are virtualized by software. As virtualized network devices and 324 functions (e.g. switches, routers, NAT, FW and ID, etc.) can be 325 connected and disconnected in almost any order in seconds, it is 326 difficult and unnecessary for a REST API to fix a resource model for 327 the clients. 329 To cope with such rapid changes without frequent updates to the 330 clients, a bottom-up design of REST API is more effective, where a 331 client can interact with a resource without knowing all its 332 connections. To follow this design, a REST API only fixes the 333 hypertext formats at design time, and the clients can use hypertext- 334 driven navigation to discover the resource identifications and 335 connections at runtime. 337 2.2. REST API Design Rules 339 Roy Fielding explains how REST API should be driven by hypermedia 340 (hypermedia constraint) with 6 rules as quoted below [Fielding2008], 341 (the rules are numbered here for ease of reference): 343 R1. A REST API should not be dependent on any single communication 344 protocol, though its successful mapping to a given protocol may be 345 dependent on the availability of metadata, choice of methods, etc. 346 In general, any protocol element that uses a URI for identification 347 must allow any URI scheme to be used for the sake of that 348 identification. [Failure here implies that identification is not 349 separated from interaction.] 351 R2. A REST API should not contain any changes to the communication 352 protocols aside from filling-out or fixing the details of 353 underspecified bits of standard protocols, such as HTTP's PATCH 354 method or Link header field. Workarounds for broken implementations 355 (such as those browsers stupid enough to believe that HTML defines 356 HTTP's method set) should be defined separately or at least in 357 appendices, with an expectation that the workaround will eventually 358 be obsolete. [Failure here implies that the resource interfaces are 359 object-specific, not generic.] 360 R3. A REST API should spend almost all of its descriptive effort in 361 defining the media type(s) used for representing resources and 362 driving application state, or in defining extended relation names 363 and/or hypertext-enabled mark-up for existing standard media types. 364 Any effort spent describing what methods to use on what URIs of 365 interest should be entirely defined within the scope of the 366 processing rules for a media type (and, in most cases, already 367 defined by existing media types). [Failure here implies that out-of- 368 band information is driving interaction instead of hypertext.] 370 R4. A REST API must not define fixed resource names or hierarchies 371 (an obvious coupling of client and server). Servers must have the 372 freedom to control their own namespace. Instead, allow servers to 373 instruct clients on how to construct appropriate URIs, such as is 374 done in HTML forms and URI templates, by defining those instructions 375 within media types and link relations. [Failure here implies that 376 clients are assuming a resource structure due to out-of band 377 information, such as a domain-specific standard, which is the data- 378 oriented equivalent to RPC's functional coupling]. 380 R5. A REST API should never have "typed" resources that are 381 significant to the client. Specification authors may use resource 382 types for describing server implementation behind the interface, but 383 those types must be irrelevant and invisible to the client. The only 384 types that are significant to a client are the current 385 representation's media type and standardized relation names. [ditto] 387 R6. A REST API should be entered with no prior knowledge beyond the 388 initial URI (bookmark) and set of standardized media types that are 389 appropriate for the intended audience (i.e., expected to be 390 understood by any client that might use the API). From that point on, 391 all application state transitions must be driven by client selection 392 of server-provided choices that are present in the received 393 representations or implied by the user's manipulation of those 394 representations. The transitions may be determined (or limited by) 395 the client's knowledge of media types and resource communication 396 mechanisms, both of which may be improved on-the-fly (e.g., code-on- 397 demand). [Failure here implies that out-of-band information is 398 driving interaction instead of hypertext.] 400 Here "hypertext" is used as a synonym for "hypermedia" which refers 401 to data that combine control information with presentation 402 information. 404 Content negotiation is another important part of REST API. HTTP 1.1 405 supports three types of content negotiations [RFC2616]: 1) server- 406 driven where the origin server determines the representation for the 407 user agent, based on user agent's preferences; 2) agent-driven where 408 the user agent selects the representation from available ones on the 409 server; 3) transparent where a cache combines the two types of 410 content negotiation. 412 The disadvantages of server-driven negotiation include: 1) the 413 origin server cannot accurately determine what is best for the user 414 agent; 2) it requires user agent to send preference on every request; 415 3) it complicates the implementation of origin servers; 4) it may 416 limit a public cache's ability to use the same response for multiple 417 user agents. Agent-driven negotiation avoids these problems but it 418 requires a second request to retrieve the best representation, which 419 is inefficient. 421 An alternative to the above negotiation mechanisms is to express the 422 available media types in the REST API. This approach enables agent- 423 driven negotiation without the need for a second request, as the 424 user agent can select the best representation from the REST API 425 directly. The disadvantage of this approach is that an origin server 426 cannot change media types at runtime. But in most cases, the 427 available media types for a REST API are unlikely to change 428 frequently. For this reason, we introduce a new rule in addition to 429 R1-R6 from Fielding [Fielding2008]: 431 R7. A resource with multiple representations should allow a 432 representation be selected from the resource [Failure here implies 433 that identification is not separated from representation]. 435 These rules should be followed by any SDN Northbound API designers, 436 unless there is a good reason to do otherwise. 438 In addition to these generic rules, REST API design for SDN should 439 also facilitate the implementation of CLI (Command-Line Interface) 440 that has much more flexibility than a GUI. A CLI command typically 441 consists of four parts: 443 - 445 For example, OpenStack [OpenStack] Neutron CLI syntax for deleting a 446 network gateway is: 448 neutron net-gateway-delete NET-GATEWAY-ID 450 where is "neutron," is "net-gateway," and 451 is "delete." The CLI interpreter provides a command- 452 based presentation layer to the user by translating the command into 453 a REST API request and the hypertext response into line-based output. 455 The following REST API design patterns can be easily supported by a 456 CLI interpreter as these design patterns are independent of the 457 presentation layers the clients choose to implement over the REST 458 API. Furthermore, certain design patterns facilitate the 459 translations between commands and REST API messages. For example, 460 the URI pattern in 3.3 makes it easy to translate the and 461 parts of a command into the resource URI, while the 462 factory and update patterns in 3.7 make it easy to translate the 463 and parts of a command into the proper 464 request. 466 The following sections describe some design patterns useful for 467 designing REST APIs in the SDN domain. 469 3. The Design Patterns 471 3.1. Content Negotiation 473 In a well-designed REST API, the identification (URI), 474 representation (hypertext), and interaction (e.g. HTTP) should be 475 orthogonal, such that each of them can evolve and be modified 476 independently without breaking the API. 478 Therefore, a media type should not be included in the identification 479 (URI), because such identification limits the ability for the server 480 to evolve the representation and identification independently, and 481 the ability for clients of different capabilities to reuse the same 482 identification. 484 Instead, any media type should be removed from the URI, and clients 485 can use HTTP 1.1 content negotiation mechanism to request different 486 media types from the same URI. Using the HTTP 1.1 header Accept, 487 clients can define their preferred media types following [RFC2046]. 488 The following examples show sample HTTP requests that illustrate 489 clients retrieve the network list information in JSON and XML by 490 accessing the same URI. 492 GET /networks HTTP/1.1 493 Host: localhost:8080 494 Accept: application/json 496 GET /networks HTTP/1.1 497 Host: localhost:8080 498 Accept: text/xml 500 3.2. Hyperlink-Driven 502 One important REST principle is that the REST API must be hypertext 503 driven. If resource URIs are predefined by some out-of-band 504 mechanism, the controller will lose the freedom to change the URIs 505 when it relocates the resources. Such resource reorganization is 506 critical, as SDN controllers are expected to evolve and migrate 507 rapidly to support various applications. 509 To respect the REST constraint, a REST API should remove any fixed 510 URI from the REST APIs, except a single entry URI to the API, from 511 which other URIs are revealed to a client through hypertext-based 512 interactions between the client and the controller. In this 513 hypertext-driven approach, the meaning of each URI is defined by the 514 hypertext in which it occurs and its value can be changed by the 515 controller without changing its meaning, thus leading to a loosely- 516 coupled REST architecture. 518 The common way to assign a meaning to a URI in HTML/XML is to use 519 the rel attribute of link element. The following examples illustrate 520 this mechanism by showing the sample HTTP request and responses. 521 Here we assume the URI template to a network is /networks/{net-id}, 522 which was obtained from the entry URI. 524 HTTP Request to retrieve a XML or JSON representation of a network 525 resource: 527 GET /networks/net1 HTTP/1.1 528 Host: localhost:8080 529 Accept: text/xml, application/json 531 HTTP Response that contains a XML representation of the network 532 resource with links to the connected ports and subnets resources: 534 HTTP/1.1 200 OK 535 Content-Type: text/xml 537 538 539 540 541 HTTP Response that contains a JSON representation of the network 542 resource with the same links in JSON format: 544 HTTP/1.1 200 OK 545 Content-Type: application/json 547 { 548 "network": { 549 "links": [ 550 {"rel":"ports", 551 "href":"/networks/net1/ports"}, 552 {"rel":"subnets", 553 "href":"/networks/net1/subnets"} 554 ] 555 } 556 } 558 The rel attribute can be absolute URI as well. The values of these 559 attributes will be defined by a REST API and cannot be changed by 560 different implementations of the API. Based on these attributes and 561 the hypertext structure, a client can select the correct resource 562 URI to follow and at the same time allow the controller to change 563 the resource URI. 565 3.3. URI Pattern 567 The design of URI namespace must allow the server to change current 568 resource organization and add new resources in a consistent way. For 569 this purpose, we propose to use design pattern "type/variable" or 570 "collection/member" pairs for URI templates, to prefix each variable 571 by a type, which serves as an extension point of the URI template. 573 An example is to use types "tenant" and "networks" in one URI to 574 identify the networks owned by a tenant: 576 {entry}/tenants/{tid}/networks/{nid}. 578 3.3.1. Entry URI 580 The entry URI is the absolute URI to a REST API implementation, e.g. 581 http://www.huawei.com/neutron. By following the definition of this 582 URI scheme through HTTP, the client can dereference this URI with a 583 HTTP GET. The response will return the hyperlinks for accessing the 584 entities supported by this implementation. 586 If an API has more than one version, the entry URI could identify a 587 specific version of the REST API, e.g. 588 http://www.huawei.com/neutron/v2.0. The server can also use a 589 generic API, like http://www.huawei.com/neutron, to point to the 590 latest version, or redirect the clients to the appropriate version 591 based on their credential or capability. 593 3.4. Navigation Pattern 595 The most basic interaction with a REST API is to navigate from an 596 entry URI to a desired resource to obtain its current representation. 597 In this framework, the navigation is performed by following a series 598 of hyperlinks contained in the response. 600 The following XML Schema shows an example for accessing the network 601 entity. The returned network_list representation contains a list of 602 network hyperlinks by which clients can access a specific network. 604 605 element networks { 606 ... 607 element link { 608 attribute rel {"network"} 609 attribute id {text} 610 attribute href {xs:anyURI} 611 }* 612 element link { 613 attribute rel {"add"} 614 attribute id {text} 615 attribute href {xs:anyURI} 616 } 617 element link { 618 attribute rel {"search"} 619 attribute id {text} 620 attribute href {xs:anyURI} 621 } 622 } 623 625 The following example shows the HTTP request and responses for the 626 network_list representation, where the links consist of relative 627 URIs. 629 HTTP request to retrieve the representation of a collection of 630 networks: 632 GET /networks HTTP/1.1 633 Host: localhost:8080 634 Accept: text/xml, application/json 636 HTTP response that contains a XML representation with a list of 637 links to the network in the collection: 639 HTTP/1.1 200 OK 640 Content-Type: text/xml 642 643 644 645 646 647 649 651 3.5. Redirection Pattern 653 HTTP 1.1 redirection [RFC2616] can be used to inform a client the 654 existence of new service and/or new location of a resource. For 655 example, the following request-response interaction allows a client 656 to learn the new location of the update service: 658 HTTP request: 660 GET /networks/net1/update HTTP/1.1 661 Host: localhost:8080 662 Accept: text/xml, application/json 664 HTTP response: 666 HTTP/1.1 301 Moved Permanently 667 Location: /networks/net1/new_update 669 One primary advantage of redirection is that a REST API does not 670 have to change its media types. The disadvantage is that the REST 671 API cannot delete the redirecting resource (e.g. 673 /networks/net1/update) to claim the memory it takes. However, it is 674 possible to delete the redirecting resources after a certain 675 transition period, when most clients have learnt the new service and 676 the redirection is no longer needed. 678 3.6. Filter and Search Patterns 680 By default, the representation of the navigation pattern contains 681 only the hyperlink for each listed entity resource. This can 682 effectively reduce the representation size, especially when the 683 number of entities is large. This however may not be efficient for 684 other use cases. For example, clients may need to retrieve the names 685 of all entities but not the entire representations. With current 686 design, this is impossible because the client has to retrieve the 687 entire network representation to get the name in it. 689 The filter pattern is designed to address this issue. The pattern 690 allows client to request additional content using 691 "?attributes={name1,...,nameN}" URI query string. As shown in the 692 following, the client requests the name and id elements in addition 693 to the default content. 695 HTTP Request: 697 GET /networks?attributes=name,id HTTP/1.1 698 Host: localhost:8080 699 Accept: text/xml, application/json 701 HTTP Response: 703 HTTP/1.1 200 OK 704 Content-Type: text/xml 706 707 708 myNet 709 net1 710 711 712 713 715 716 If a tenant has a large number of entities, it would be very 717 inefficient for the client to use the navigation pattern to locate a 718 specific entity. To address this problem, the search pattern is 719 designed by providing a hyperlink containing a URI template to allow 720 clients to submit queries consisting of key-value pairs. The 721 following example shows HTTP request and response for a search 722 pattern to find all networks that are shared between tenants: 724 HTTP Request with a search parameter shared=true: 726 GET /networks/search?shared=true HTTP/1.1 727 Host: localhost:8080 728 Accept: text/xml, application/json 730 HTTP Response that contains links to two network resources (i.e. 731 net1 and net2) that are shared: 733 HTTP/1.1 200 OK 734 Content-Type: text/xml 736 737 738 739 741 3.7. Factory and Update Pattern 743 When creating or updating a resource, clients may have to deal with 744 the special constraints on the resource attributes: some of the 745 attributes are required in creating a resource, while some 746 attributes are read only and cannot be updated. 748 These constraints of attributes are usually implicit, where 749 programmers have to check the documents to identify these 750 constraints. This is inefficient and error prone. Furthermore, the 751 server may change these rules in the future, which could compromise 752 the clients. 754 To address the issue, the framework here applies an explicit 755 approach of enforcing these constraints. Rather than presenting the 756 constraints in documents, we apply a form-based approach to enforce 757 these constraints at runtime. 759 3.7.1. Factory Pattern 761 The factory pattern returns a form to the client claiming the 762 constraints on the attributes. In the form, all the required 763 attributes are marked required=true. The form also provides default 764 values for some unmarked attributes. This allows clients to be 765 programmed adaptively to cope with these explicit constraints. In 766 particular, the attribute method of the form element indicates that 767 the client should submit the filled-out form by the HTTP command 768 POST. 770 This form can be defined as follows using RELAX-NG XML Schema: 772 773 element form { 774 attribute method {"POST"} 775 element network { 776 element id { 777 attribute required {"true"} text 778 } 779 element name { text } 780 element admin { text } 781 element shared { text } 782 element tenant { attribute required {"false"} } 783 } 784 element link { 785 attribute rel {"target"} 786 attribute id {text} 787 attribute href {xs:anyURI} 788 }? 789 } 790 792 The following shows such an example form of factory pattern about 793 creating a new virtual network. Here we assume that the URI for 794 creating a new virtual network is /networks/factory. By default, an 795 attribute is marked as required=false. 797 HTTP Request to retrieve a representation of the factory resource: 799 GET /networks/factory HTTP/1.1 800 Host: localhost:8080 801 Accept: text/xml, application/json 802 HTTP Response that contains an empty XML form for the client to fill 803 and submit to the target resource in order to create a network: 805 HTTP/1.1 200 OK 806 Content-Type: text/xml 808
809 810 811 812 true 813 true 814 815 816 817
819 The resource created by one factory can be another factory, to form 820 a factory chain. The organization of the chain is not static but 821 determined by the hypertext from a REST API at runtime. 823 3.7.2. Update Pattern 825 Similar to the factory pattern, the update pattern also returns a 826 form to the client showing explicit rules of updates. In this case, 827 the attributes which are allowed to be updated are included in the 828 form, while the missing attributes are read only. In addition, the 829 method is now PUT to comply with the REST constraint of uniform 830 interface. 832 This form can be defined as follows using RELAX-NG XML Schema: 834 835 element form { 836 attribute method {"PUT"} 837 element network { 838 element name { text } 839 element admin { text } 840 element shared { text } 841 } 842 element link { 843 attribute rel {"target"} 844 attribute id {text} 845 attribute href {xs:anyURI} 846 }? 847 } 848 850 The following shows such an example form of the update pattern about 851 updating an existed virtual network. Here we assume the ID of the 852 virtual network is net1 and the corresponding URI is 853 /networks/net1/update. 855 HTTP Request to retrieve a representation of the network modifier 856 resource: 858 GET /networks/net1/update HTTP/1.1 859 Host: localhost:8080 860 Accept: text/xml, application/json 862 HTTP Response that contains a pre-filled XML form for the client to 863 change and submit to the target resource in order to update the 864 network: 866 HTTP/1.1 200 OK 867 Content-Type: text/xml 869
870 871 myNet1 872 true 873 true 874 875 876
878 4. Cache Pattern 880 Clients accessing the hypertext-driven REST API for the first time 881 should start from the entry URI and follow the returned hyperlinks 882 to access other resources. This provides the REST API with desired 883 flexibility and extensibility including the loosely-coupled and late 884 binding features. After the first visit, the client and intermediary 885 proxies should be able to cache the returned representations 886 according to HTTP 1.1. Cache Control [RFC2616] to reduce network 887 traffic for future interactions with the server. An efficient 888 approach to cache in Northbound API of SDN is described in 889 [Zhou2014a] and [Zhou2014b]. 891 5. Security Considerations 893 895 6. IANA Considerations 897 899 7. Conclusions 901 This document summarizes the REST rules and design patterns for SDN 902 Northbound API, using OpenStack Northbound virtual network 903 management API as an example. With these rules and patterns, it will 904 lead to a REST API that is scalable, extensible, and interoperable 905 as the true RESTful approach promises. In addition, it avoids some 906 common mistakes in REST API designs, and it can achieve desired 907 quality and consistency in SDN Northbound API designs. 909 8. References 911 8.1. Normative References 913 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 914 Extensions (MIME) Part Two: Media Types", RFC 2046, 915 November 1996. 917 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 918 Requirement Levels", BCP 14, RFC 2119, March 1997. 920 [RFC2234] Crocker, D. and Overell, P.(Editors), "Augmented BNF for 921 Syntax Specifications: ABNF", RFC 2234, Internet Mail 922 Consortium and Demon Internet Ltd., November 1997. 924 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, 925 L., Leach, P., and T. Berners-Lee, "Hypertext Transfer 926 Protocol -- HTTP/1.1", RFC 2616, June 1999. 928 8.2. Informative References 930 [SDN-Arch] 931 https://www.opennetworking.org/images/stories/downloads/wo 932 rking-groups/charter-architecture-framework.pdf 934 [Cassandras2008] C. G. Cassandras, et al, Introduction to Discrete 935 Event Systems, second edition, Chpater 4, Springer, 2008. 937 [Click] Click, . 939 [Fielding2000] R. T. Fielding, Architectural styles and the design 940 of network-based software architectures, Ph.D. 941 Dissertation, University of California, Irvine, 2000, 942 . 945 [Fielding2008] R. T. Fielding, "REST API must be hypertext driven," 946 28 October, 2008, 947 . 950 [Floodlight] http://www.projectfloodlight.org/floodlight/. 952 [Jensen1997] K. Jensen, Coloured Petri Nets, Springer Verlag, 1997. 954 [Li2011] L. Li and W. Chou, Design and describe REST API without 955 violating REST: a Petri net based approach, Proceedings of 956 the 2011 IEEE International Conference on Web Services, 957 508-515, 2011. 959 [OpenFlow] Open Networking Foundation, "The OpenFlow 1.4.0 960 Specification.", 961 . 965 [OpenStack] OpenStack Foundation. OpenStack networking 966 administration guide, Feb 2013, 967 http://docs.openstack.org/trunk/openstack-network/ 968 admin/content/index.html. 970 [Pyretic] Pyretic, . 972 [Richardson2007] Leonard Richardson, Sam Ruby, Restful Web Services, 973 O'Reilly, 2007. 975 [Zhou2014a] Wei Zhou, Li Li, Min Luo, Wu Chou: REST API Design 976 Patterns for SDN Northbound API, The 28th IEEE 977 International Conference on Advanced Information 978 Networking and Applications Workshops (AINA-2014), pages 979 358-365, Victoria, BC, Canada, May 13-16, 2014. 981 [Zhou2014b] Wei Zhou, Li Li, Wu Chou: SDN Northbound REST API with 982 Efficient Caches, to appear in ICWS2014, Anchorage, Alaska, 983 June 26-July 2, 2014. 985 Authors' Addresses 987 Wei Zhou 988 Huawei Technologies co. ltd. 989 Email: sky.zhouwei@huawei.com 991 Li Li 992 Huawei Technologies co. ltd. 993 Email: li.nj.li@huawei.com 995 Min Luo 996 Huawei Technologies co. ltd. 997 Email: min.ch.luo@huawei.com 999 Wu Chou 1000 Huawei Technologies co. ltd. 1001 Email: wu.chou@huawei.com