< draft-bierman-netconf-yang-api-00.txt   draft-bierman-netconf-yang-api-01.txt >
Network Working Group A. Bierman Network Working Group A. Bierman
Internet-Draft YumaWorks Internet-Draft YumaWorks
Intended status: Standards Track M. Bjorklund Intended status: Standards Track M. Bjorklund
Expires: December 1, 2012 Tail-f Systems Expires: June 3, 2013 Tail-f Systems
May 30, 2012 November 30, 2012
YANG-API Protocol YANG-API Protocol
draft-bierman-netconf-yang-api-00 draft-bierman-netconf-yang-api-01
Abstract Abstract
This document describes a RESTful protocol that provides a This document describes a RESTful protocol that provides a
programmatic interface over HTTP for accessing data defined in YANG, programmatic interface over HTTP for accessing data defined in YANG,
using the datastores defined in NETCONF. using the datastores defined in NETCONF.
Status of this Memo Status of this Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
skipping to change at page 1, line 33 skipping to change at page 1, line 33
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on December 1, 2012. This Internet-Draft will expire on June 3, 2013.
Copyright Notice Copyright Notice
Copyright (c) 2012 IETF Trust and the persons identified as the Copyright (c) 2012 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 1.1. Simple Subset of NETCONF Functionality . . . . . . . . . . 4
1.1.1. NETCONF . . . . . . . . . . . . . . . . . . . . . . . 5 1.2. Data Model Driven API . . . . . . . . . . . . . . . . . . 5
1.1.2. HTTP . . . . . . . . . . . . . . . . . . . . . . . . . 5 1.3. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6
1.1.3. YANG . . . . . . . . . . . . . . . . . . . . . . . . . 6 1.3.1. NETCONF . . . . . . . . . . . . . . . . . . . . . . . 6
1.1.4. Terms . . . . . . . . . . . . . . . . . . . . . . . . 7 1.3.2. HTTP . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.2. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 7 1.3.3. YANG . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.2.1. Resource URI Map . . . . . . . . . . . . . . . . . . . 8 1.3.4. Terms . . . . . . . . . . . . . . . . . . . . . . . . 8
1.2.2. YANG-API Message Examples . . . . . . . . . . . . . . 8 1.4. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 8
1.4.1. Resource URI Map . . . . . . . . . . . . . . . . . . . 9
1.4.2. YANG-API Message Examples . . . . . . . . . . . . . . 9
2. Framework . . . . . . . . . . . . . . . . . . . . . . . . . . 15 2. Framework . . . . . . . . . . . . . . . . . . . . . . . . . . 15
2.1. Message Model . . . . . . . . . . . . . . . . . . . . . . 15 2.1. Message Model . . . . . . . . . . . . . . . . . . . . . . 15
2.2. Resource Model . . . . . . . . . . . . . . . . . . . . . . 15 2.2. Resource Model . . . . . . . . . . . . . . . . . . . . . . 15
2.2.1. YANG-API Resource Types . . . . . . . . . . . . . . . 15 2.2.1. YANG-API Resource Types . . . . . . . . . . . . . . . 15
2.2.2. Resource Discovery . . . . . . . . . . . . . . . . . . 16 2.2.2. Resource Discovery . . . . . . . . . . . . . . . . . . 16
2.3. Datastore Model . . . . . . . . . . . . . . . . . . . . . 16 2.3. Datastore Model . . . . . . . . . . . . . . . . . . . . . 16
2.3.1. Content Model . . . . . . . . . . . . . . . . . . . . 17 2.3.1. Content Model . . . . . . . . . . . . . . . . . . . . 17
2.3.2. Editing Model . . . . . . . . . . . . . . . . . . . . 17 2.3.2. Editing Model . . . . . . . . . . . . . . . . . . . . 17
2.3.3. Locking Model . . . . . . . . . . . . . . . . . . . . 19 2.3.3. Locking Model . . . . . . . . . . . . . . . . . . . . 19
2.3.4. Persistence Model . . . . . . . . . . . . . . . . . . 20 2.3.4. Persistence Model . . . . . . . . . . . . . . . . . . 19
2.3.5. Defaults Model . . . . . . . . . . . . . . . . . . . . 20 2.3.5. Defaults Model . . . . . . . . . . . . . . . . . . . . 19
2.4. Transaction Model . . . . . . . . . . . . . . . . . . . . 20 2.4. Transaction Model . . . . . . . . . . . . . . . . . . . . 20
2.5. Extensibility Model . . . . . . . . . . . . . . . . . . . 21 2.5. Extensibility Model . . . . . . . . . . . . . . . . . . . 20
2.6. Versioning Model . . . . . . . . . . . . . . . . . . . . . 21 2.6. Versioning Model . . . . . . . . . . . . . . . . . . . . . 20
2.7. Retrieval Filtering Model . . . . . . . . . . . . . . . . 22 2.7. Retrieval Filtering Model . . . . . . . . . . . . . . . . 21
2.8. Access Control Model . . . . . . . . . . . . . . . . . . . 22 2.8. Access Control Model . . . . . . . . . . . . . . . . . . . 21
3. Operations . . . . . . . . . . . . . . . . . . . . . . . . . . 24 3. Operations . . . . . . . . . . . . . . . . . . . . . . . . . . 22
3.1. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . 24 3.1. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . 22
3.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 3.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
3.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 3.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
3.4. POST . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 3.4. POST . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
3.5. PUT . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 3.5. PUT . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
3.6. PATCH . . . . . . . . . . . . . . . . . . . . . . . . . . 29 3.6. PATCH . . . . . . . . . . . . . . . . . . . . . . . . . . 27
3.7. DELETE . . . . . . . . . . . . . . . . . . . . . . . . . . 29 3.7. DELETE . . . . . . . . . . . . . . . . . . . . . . . . . . 27
3.8. Query Parameters . . . . . . . . . . . . . . . . . . . . . 30 3.8. Query Parameters . . . . . . . . . . . . . . . . . . . . . 28
3.8.1. "config" Parameter . . . . . . . . . . . . . . . . . . 30 3.8.1. "config" Parameter . . . . . . . . . . . . . . . . . . 28
3.8.2. "depth" Parameter . . . . . . . . . . . . . . . . . . 31 3.8.2. "depth" Parameter . . . . . . . . . . . . . . . . . . 29
3.8.3. "format" Parameter . . . . . . . . . . . . . . . . . . 32 3.8.3. "format" Parameter . . . . . . . . . . . . . . . . . . 30
3.8.4. "insert" Parameter . . . . . . . . . . . . . . . . . . 32 3.8.4. "insert" Parameter . . . . . . . . . . . . . . . . . . 30
3.8.5. "point" Parameter . . . . . . . . . . . . . . . . . . 33 3.8.5. "point" Parameter . . . . . . . . . . . . . . . . . . 31
3.8.6. "select" Parameter . . . . . . . . . . . . . . . . . . 34 3.8.6. "select" Parameter . . . . . . . . . . . . . . . . . . 32
3.9. RPC Operations . . . . . . . . . . . . . . . . . . . . . . 34 3.9. Protocol Operations . . . . . . . . . . . . . . . . . . . 32
3.9.1. Data Model Specific Operations . . . . . . . . . . . . 35 4. Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
4. Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 4.1. Request URI Structure . . . . . . . . . . . . . . . . . . 34
4.1. Request URI Structure . . . . . . . . . . . . . . . . . . 36 4.2. Message Headers . . . . . . . . . . . . . . . . . . . . . 35
4.2. Message Headers . . . . . . . . . . . . . . . . . . . . . 37 4.3. Message Encoding . . . . . . . . . . . . . . . . . . . . . 36
4.3. Message Encoding . . . . . . . . . . . . . . . . . . . . . 38 4.4. Return Status . . . . . . . . . . . . . . . . . . . . . . 36
4.4. Return Status . . . . . . . . . . . . . . . . . . . . . . 38 4.5. Message Caching . . . . . . . . . . . . . . . . . . . . . 37
4.5. Message Caching . . . . . . . . . . . . . . . . . . . . . 39 5. Resources . . . . . . . . . . . . . . . . . . . . . . . . . . 38
5. Resources . . . . . . . . . . . . . . . . . . . . . . . . . . 40 5.1. API Resource (/yang-api) . . . . . . . . . . . . . . . . . 38
5.1. API Resource (/yang-api) . . . . . . . . . . . . . . . . . 40 5.1.1. /yang-api/datastore . . . . . . . . . . . . . . . . . 38
5.1.1. /yang-api/capabilities . . . . . . . . . . . . . . . . 40 5.1.2. /yang-api/modules . . . . . . . . . . . . . . . . . . 38
5.1.2. /yang-api/datastore . . . . . . . . . . . . . . . . . 43 5.1.3. /yang-api/operations . . . . . . . . . . . . . . . . . 38
5.1.3. /yang-api/operations . . . . . . . . . . . . . . . . . 44 5.1.4. /yang-api/version . . . . . . . . . . . . . . . . . . 40
5.1.4. /yang-api/modules . . . . . . . . . . . . . . . . . . 46 5.2. Datastore Resource . . . . . . . . . . . . . . . . . . . . 41
5.1.5. /yang-api/transaction . . . . . . . . . . . . . . . . 48 5.3. Data Resource . . . . . . . . . . . . . . . . . . . . . . 41
5.1.6. /yang-api/version . . . . . . . . . . . . . . . . . . 48
5.2. Datastore Resource . . . . . . . . . . . . . . . . . . . . 49
5.3. Data Resource . . . . . . . . . . . . . . . . . . . . . . 49
5.3.1. Encoding YANG Instance Identifiers in the Request 5.3.1. Encoding YANG Instance Identifiers in the Request
URI . . . . . . . . . . . . . . . . . . . . . . . . . 50 URI . . . . . . . . . . . . . . . . . . . . . . . . . 42
5.3.2. Identifying YANG-defined Data Resources . . . . . . . 52 5.3.2. Identifying YANG-defined Data Resources . . . . . . . 44
5.3.3. Identifying Optional Keys . . . . . . . . . . . . . . 53 5.3.3. Identifying Optional Keys . . . . . . . . . . . . . . 45
5.3.4. Data Resource Retrieval . . . . . . . . . . . . . . . 53 5.3.4. Data Resource Retrieval . . . . . . . . . . . . . . . 45
5.4. Operation Resource . . . . . . . . . . . . . . . . . . . . 55 5.4. Operation Resource . . . . . . . . . . . . . . . . . . . . 47
5.4.1. Encoding Operation Input Parameters . . . . . . . . . 56 5.4.1. Encoding Operation Input Parameters . . . . . . . . . 48
5.4.2. Encoding Operation Output Parameters . . . . . . . . . 57 5.4.2. Encoding Operation Output Parameters . . . . . . . . . 49
5.4.3. Identifying YANG-defined Operation Resources . . . . . 58 5.4.3. Identifying YANG-defined Operation Resources . . . . . 50
5.5. Transaction Resource . . . . . . . . . . . . . . . . . . . 58 6. Error Reporting . . . . . . . . . . . . . . . . . . . . . . . 51
5.5.1. Creating a Transaction Resource . . . . . . . . . . . 59 6.1. Error Response Message . . . . . . . . . . . . . . . . . . 52
5.5.2. Editing a Transaction Datastore . . . . . . . . . . . 60 7. RelaxNG Grammar . . . . . . . . . . . . . . . . . . . . . . . 55
5.5.3. Deleting a Transaction Resource . . . . . . . . . . . 61 8. YANG-API module . . . . . . . . . . . . . . . . . . . . . . . 56
5.5.4. Transaction Operations . . . . . . . . . . . . . . . . 62 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 58
6. Error Reporting . . . . . . . . . . . . . . . . . . . . . . . 65 10. Security Considerations . . . . . . . . . . . . . . . . . . . 59
6.1. Error Response Message . . . . . . . . . . . . . . . . . . 66 11. Change Log . . . . . . . . . . . . . . . . . . . . . . . . . . 60
7. RelaxNG Grammar . . . . . . . . . . . . . . . . . . . . . . . 69 11.1. 00-01 . . . . . . . . . . . . . . . . . . . . . . . . . . 60
8. YANG-API module . . . . . . . . . . . . . . . . . . . . . . . 70 12. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 61
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 73 13. Example YANG Module . . . . . . . . . . . . . . . . . . . . . 63
10. Security Considerations . . . . . . . . . . . . . . . . . . . 74 14. Normative References . . . . . . . . . . . . . . . . . . . . . 67
11. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 75 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 68
12. Example YANG Module . . . . . . . . . . . . . . . . . . . . . 78
13. Normative References . . . . . . . . . . . . . . . . . . . . . 82
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 83
1. Introduction 1. Introduction
There is a need for standard mechanisms to allow WEB applications to There is a need for standard mechanisms to allow WEB applications to
access the configuration data, operational data, and data-model access the configuration data, operational data, and data-model
specific RPC operations within a networking device, in a modular and specific protocol operations within a networking device, in a modular
extensible manner. and extensible manner.
This document describes a RESTful protocol called YANG-API, running This document describes a RESTful protocol called YANG-API, running
over HTTP [RFC2616], for accessing data defined in YANG [RFC6020], over HTTP [RFC2616], for accessing data defined in YANG [RFC6020],
using datastores defined in NETCONF [RFC6241]. using datastores defined in NETCONF [RFC6241].
The NETCONF protocol defines configuration datastores and a set of The NETCONF protocol defines configuration datastores and a set of
Create, Retrieve, Update, Delete (CRUD) operations that can be used Create, Retrieve, Update, Delete (CRUD) operations that can be used
to access these datastores. The YANG language defines the syntax and to access these datastores. The YANG language defines the syntax and
semantics of datastore content and operational data. RESTful semantics of datastore content and operational data. RESTful
operations are used to access the hierarchical data within a operations are used to access the hierarchical data within a
skipping to change at page 4, line 33 skipping to change at page 4, line 33
A RESTful API can be created that provides CRUD operations on a A RESTful API can be created that provides CRUD operations on a
NETCONF datastore containing YANG-defined data. This can be done in NETCONF datastore containing YANG-defined data. This can be done in
a simplified manner, compatible with HTTP and RESTful design a simplified manner, compatible with HTTP and RESTful design
principles. Since NETCONF protocol operations are not relevant, the principles. Since NETCONF protocol operations are not relevant, the
user should not need any prior knowledge of NETCONF in order to use user should not need any prior knowledge of NETCONF in order to use
the RESTful API. the RESTful API.
Configuration data and state data are exposed as resources that can Configuration data and state data are exposed as resources that can
be retrieved with the GET method. Resources representing be retrieved with the GET method. Resources representing
configuration data can be modified with the DELETE, PATCH, POST, and configuration data can be modified with the DELETE, PATCH, POST, and
PUT methods. Data-model specific RPC operations defined with the PUT methods. Data-model specific protocol operations defined with
YANG "rpc" statement can be invoked with the POST method. the YANG "rpc" statement can be invoked with the POST method.
1.1. Simple Subset of NETCONF Functionality
The framework and meta-model used for a RESTful API does not need to The framework and meta-model used for a RESTful API does not need to
mirror those used by the NETCONF protocol. It just needs to be mirror those used by the NETCONF protocol. It just needs to be
compatible with NETCONF. A simplified framework and protocol is compatible with NETCONF. A simplified framework and protocol is
needed that aligns with the three NETCONF datastores (candidate, needed that utilizes the three NETCONF datastores (candidate,
running, startup). A simplified yet more powerful transaction model running, startup), but hides the complexity of multiple datastores
is needed that exposes the proper functionality without over- from the client.
restricting server design.
A simplified transaction model is needed that allows basic CRUD
operations on a hierarchy of conceptual resources. This represents a
limited subset of the transaction capabilities of the NETCONF
protocol.
Applications that require more complex transaction capabilities might
consider NETCONF instead of YANG-API. The following transaction
features are not provided in YANG-API:
o datastore locking (full or partial)
o candidate datastore
o validate operation
o confirmed-commit procedure
The RESTful API is not intended to replace NETCONF, but rather The RESTful API is not intended to replace NETCONF, but rather
provide an additional simplified interface that follows RESTful provide an additional simplified interface that follows RESTful
principles and is compatible with a resource-oriented device principles and is compatible with a resource-oriented device
abstraction. It is expected that applications that need the full abstraction. It is expected that applications that need the full
feature set of NETCONF such as notifications will continue to use feature set of NETCONF such as notifications will continue to use
NETCONF. NETCONF.
The following figure shows the system components: The following figure shows the system components:
+-----------+ +-----------------+ +-----------+ +-----------------+
| WEB app | <-------> | | | WEB app | <-------> | |
+-----------+ HTTP | network device | +-----------+ HTTP | network device |
| | | |
+-----------+ | +-----------+ | +-----------+ | +-----------+ |
| NMS app | <-------> | | datastore | | | NMS app | <-------> | | datastore | |
+-----------+ NETCONF | +-----------+ | +-----------+ NETCONF | +-----------+ |
+-----------------+ +-----------------+
1.1. Terminology 1.2. Data Model Driven API
YANG-API combines the simplicity of a RESTful API over HTTP with the
predictability and automation potential of a schema-driven API.
A RESTful client using YANG-API will not use any data modelling
language to define the application-specific content of the API. The
client would discover each new child resource as it traverses the
URIs return as Location IDs to discover the server capabilities.
This approach has 3 significant weaknesses wrt/ control of complex
networking devices:
o inefficient performance: configuration APIs will be quite complex
and may require thousands of protocol messages to discover all the
schema information. Typically the data type information has to be
passed in the protocol messages, which is also wasteful overhead.
o no data model richness: without a data model, the schema-level
semantics and validation constraints are not available to the
application. Data model modules such as YANG modules serve as an
"API contract" that will be honored by the server. An application
designer can code to the data model, knowing in advance important
details about the exact protocol operations and datastore content
a conforming server implementation will support.
o no tool automation: API automation tools need some sort of content
schema to function. Such tools can automate various programming
and documentation tasks related to specific data models.
YANG-API provides the YANG module capability information supported by
the server, in case the client wants to use it. The URIs for custom
protocol operations and datastore content are predictable, based on
the YANG module definitions. Note that the YANG modules and
predictable URIs are optional to use by the client. They can be
completely ignored without any loss of protocol functionality.
Operational experience with CLI and SNMP indicates that operators
learn the 'location' of specific service or device related data and
do not expect such information to be arbitrary and discovered each
time the client opens a management session to a server.
1.3. Terminology
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP "OPTIONAL" in this document are to be interpreted as described in BCP
14, [RFC2119]. 14, [RFC2119].
1.1.1. NETCONF 1.3.1. NETCONF
The following terms are defined in [RFC6241]: The following terms are defined in [RFC6241]:
o candidate configuration datastore o candidate configuration datastore
o client o client
o configuration data o configuration data
o datastore o datastore
skipping to change at page 5, line 40 skipping to change at page 7, line 4
o datastore o datastore
o configuration datastore o configuration datastore
o protocol operation o protocol operation
o running configuration datastore o running configuration datastore
o server o server
o startup configuration datastore o startup configuration datastore
o state data o state data
o user o user
1.1.2. HTTP 1.3.2. HTTP
The following terms are defined in [RFC2616]: The following terms are defined in [RFC2616]:
o entity tag o entity tag
o fragment o fragment
o header line o header line
o message body o message body
skipping to change at page 6, line 23 skipping to change at page 7, line 32
o method o method
o path o path
o query o query
o request URI o request URI
o response body o response body
1.1.3. YANG 1.3.3. YANG
The following terms are defined in [RFC6020]: The following terms are defined in [RFC6020]:
o container o container
o data node o data node
o key leaf o key leaf
o leaf o leaf
o leaf-list o leaf-list
o list o list
o presence container (or P-container) o presence container (or P-container)
o RPC operation o RPC operation (now called protocol operation)
o non-presence container (or NP-container) o non-presence container (or NP-container)
o ordered-by system o ordered-by system
o ordered-by user o ordered-by user
1.1.4. Terms 1.3.4. Terms
The following terms are used within this document: The following terms are used within this document:
o API resource: a resource with the media type "application/ o API resource: a resource with the media type "application/
vnd.yang.api+xml" or ""application/vnd.yang.api+json". vnd.yang.api+xml" or ""application/vnd.yang.api+json".
o data resource: a resource with the media type "application/ o data resource: a resource with the media type "application/
vnd.yang.data+xml" or "application/vnd.yang.data+json". vnd.yang.data+xml" or "application/vnd.yang.data+json".
o datastore resource: a resource with the media type "application/ o datastore resource: a resource with the media type "application/
skipping to change at page 7, line 41 skipping to change at page 8, line 46
within the query portion of the request URI. within the query portion of the request URI.
o resource: a conceptual object representing a manageable component o resource: a conceptual object representing a manageable component
within a device. within a device.
o retrieval request: an operation using the GET or HEAD methods. o retrieval request: an operation using the GET or HEAD methods.
o target resource: the resource that is associated with a particular o target resource: the resource that is associated with a particular
message, identified by the "path" component of the request URI. message, identified by the "path" component of the request URI.
o transaction resource: a resource with the media type 1.4. Overview
"vnd.yang.transaction+xml" or "vnd.yang.transaction+json"
1.2. Overview
This document defines the YANG-API protocol, a RESTful API for This document defines the YANG-API protocol, a RESTful API for
accessing conceptual datastores containing data defined with YANG accessing conceptual datastores containing data defined with YANG
language. YANG-API provides an application framework and meta-model, language. YANG-API provides an application framework and meta-model,
using HTTP operations. using HTTP operations.
The YANG-API resources are accessed via a set of URIs defined in this The YANG-API resources are accessed via a set of URIs defined in this
document. The set of YANG modules supported by the server will document. The set of YANG modules supported by the server will
determine the additional data model specific operations and top-level determine the additional data model specific operations and top-level
data node resources available on the server. data node resources available on the server.
Not all YANG-API defined resources are mandatory-to-implement. The 1.4.1. Resource URI Map
server implementor may choose the specific editing model and
persistence model that is supported. The specific subset is
identified and accessible via 3 capability fields. Refer to
Section 5.1.1 for more details.
1.2.1. Resource URI Map
The URI hierarchy for the YANG-API resources consists of an entry The URI hierarchy for the YANG-API resources consists of an entry
point and up to 6 top-level resources and/or fields. Refer to point and up to 4 top-level resources and/or fields. Refer to
Section 5 for details on each URI. Section 5 for details on each URI.
/yang-api /yang-api
/capabilities
/edit-model
/persist-model
/transaction-model
/datastore /datastore
/<top-level-data-nodes> (config=true or false) /<top-level-data-nodes> (config=true or false)
/modules /modules
/module /module
/operations /operations
/lock-datastore /<custom protocol operations>
/save-datastore
/unlock-datastore
/<operations>
/transaction
/<transaction-id>
/commit
/datastore
/<top-level-data-nodes> (config=true)
/discard-changes
/exclusive-mode
/update
/validate
/version /version
1.2.2. YANG-API Message Examples 1.4.2. YANG-API Message Examples
The examples within this document use the non-normative example YANG The examples within this document use the non-normative example YANG
module defined in Section 12. module defined in Section 13.
This section shows some typical YANG-API message exchanges. This section shows some typical YANG-API message exchanges.
In these examples, the server capabilities are as follows: 1.4.2.1. Retrieve the Top-level API Resource
o the edit-model is "direct"
o the persist-model is "manual"
o the transaction-model is "none"
1.2.2.1. Retrieve the Top-level API Resource
By default, when a resource is retrieved, all of its fields are By default, when a resource is retrieved, all of its fields are
returned, but none (if any) of the nested resources are returned. returned, but none (if any) of the nested resources are returned.
Also, the default encoding is JSON. Data resources are encoded Also, the default encoding is JSON. Data resources are encoded
according to the encoding rules in [I-D.lhotka-yang-json]. according to the encoding rules in [I-D.lhotka-netmod-json].
The client starts by retrieving the top-level API resource, using the The client starts by retrieving the top-level API resource, using the
entry point URI "/yang-api". entry point URI "/yang-api".
GET /yang-api HTTP/1.1 GET /yang-api HTTP/1.1
Host: example.com Host: example.com
The server might respond as follows. The "module" lines below are The server might respond as follows. The "module" lines below are
split for display purposes only: split for display purposes only:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Date: Mon, 23 Apr 2012 17:01:00 GMT Date: Mon, 23 Apr 2012 17:01:00 GMT
Server: example-server Server: example-server
Content-Type: application/vnd.yang.api+json Content-Type: application/vnd.yang.api+json
{ {
"yang-api": { "yang-api": {
"capabilities": {
"edit-model": "direct",
"persist-model": "automatic",
"transaction-model": "none"
},
"modules": { "modules": {
"module": [ "module": [
"urn:ietf:params:xml:ns:yang:ietf-yang-api "urn:ietf:params:xml:ns:yang:ietf-yang-api
?module=ietf-yang-api&revision=2012-05-27", ?module=ietf-yang-api&revision=2012-05-27",
"example.com?module=example-jukebox "example.com?module=example-jukebox
&revision=2012-05-30" &revision=2012-05-30"
] ]
}, },
"version": "1.0" "version": "1.0"
} }
skipping to change at page 10, line 24 skipping to change at page 11, line 4
The server will return the same response either way, which might be The server will return the same response either way, which might be
as follows : as follows :
HTTP/1.1 200 OK HTTP/1.1 200 OK
Date: Mon, 23 Apr 2012 17:01:00 GMT Date: Mon, 23 Apr 2012 17:01:00 GMT
Server: example-server Server: example-server
Cache-Control: no-cache Cache-Control: no-cache
Pragma: no-cache Pragma: no-cache
Content-Type: application/vnd.yang.api+xml Content-Type: application/vnd.yang.api+xml
<yang-api> <yang-api>
<capabilities>
<edit-model>direct</edit-model>
<persist-model>automatic</persist-model>
<transaction-model>none</transaction-model>
</capabilities>
<modules> <!-- wrapped for display only --> <modules> <!-- wrapped for display only -->
<module>urn:ietf:params:xml:ns:yang:ietf-yang-api <module>urn:ietf:params:xml:ns:yang:ietf-yang-api
?module=ietf-yang-api ?module=ietf-yang-api
&amp;revision=2012-05-27</module> &amp;revision=2012-05-27</module>
<module>example.com?module=example-jukebox <module>example.com?module=example-jukebox
&amp;revision=2012-05-30</module> &amp;revision=2012-05-30</module>
</modules> </modules>
<version>1.0</version> <version>1.0</version>
</yang-api> </yang-api>
Refer to Section 3.3 for details on the GET operation. Refer to Section 3.3 for details on the GET operation.
1.2.2.2. Create New Data Resources 1.4.2.2. Create New Data Resources
To create a new "jukebox" resource, the client might send: To create a new "jukebox" resource, the client might send:
POST /yang-api/datastore/jukebox HTTP/1.1 POST /yang-api/datastore/jukebox HTTP/1.1
Host: example.com Host: example.com
If the resource is created, the server might respond: If the resource is created, the server might respond:
HTTP/1.1 201 Created HTTP/1.1 201 Created
Date: Mon, 23 Apr 2012 17:01:00 GMT Date: Mon, 23 Apr 2012 17:01:00 GMT
skipping to change at page 12, line 15 skipping to change at page 12, line 41
HTTP/1.1 201 Created HTTP/1.1 201 Created
Date: Mon, 23 Apr 2012 17:03:00 GMT Date: Mon, 23 Apr 2012 17:03:00 GMT
Server: example-server Server: example-server
Location: http://example.com/yang-api/datastore/ Location: http://example.com/yang-api/datastore/
jukebox/artist/1/album/Wasting%20Light jukebox/artist/1/album/Wasting%20Light
Last-Modified: Mon, 23 Apr 2012 17:03:00 GMT Last-Modified: Mon, 23 Apr 2012 17:03:00 GMT
ETag: b8389233a4c ETag: b8389233a4c
Refer to Section 3.4 for details on the POST operation. Refer to Section 3.4 for details on the POST operation.
1.2.2.3. Replace an Existing Data Resource 1.4.2.3. Replace an Existing Data Resource
Note: replacing a resource is a fairly drastic operation. The PATCH Note: replacing a resource is a fairly drastic operation. The PATCH
operation is often more appropriate. operation is often more appropriate.
The album sub-resource is re-added here for example purposes only. The album sub-resource is re-added here for example purposes only.
To replace the "artist" resource contents, the client might send: To replace the "artist" resource contents, the client might send:
PUT /yang-api/datastore/jukebox/artist/1 HTTP/1.1 PUT /yang-api/datastore/jukebox/artist/1 HTTP/1.1
Host: example.com Host: example.com
If-Match: b3830f23a4c If-Match: b3830f23a4c
skipping to change at page 12, line 49 skipping to change at page 13, line 31
If the resource is updated, the server might respond: If the resource is updated, the server might respond:
HTTP/1.1 204 No Content HTTP/1.1 204 No Content
Date: Mon, 23 Apr 2012 17:04:00 GMT Date: Mon, 23 Apr 2012 17:04:00 GMT
Server: example-server Server: example-server
Last-Modified: Mon, 23 Apr 2012 17:04:00 GMT Last-Modified: Mon, 23 Apr 2012 17:04:00 GMT
ETag: b27480aeda4c ETag: b27480aeda4c
Refer to Section 3.5 for details on the PUT operation. Refer to Section 3.5 for details on the PUT operation.
1.2.2.4. Patch an Existing Data Resource 1.4.2.4. Patch an Existing Data Resource
To replace just the "year" field in the "album" resource, the client To replace just the "year" field in the "album" resource, the client
might send: might send:
PATCH /yang-api/datastore/jukebox/artist/1/album/ PATCH /yang-api/datastore/jukebox/artist/1/album/
Wasting%20Light/year HTTP/1.1 Wasting%20Light/year HTTP/1.1
Host: example.com Host: example.com
If-Match: b8389233a4c If-Match: b8389233a4c
Content-Type: application/vnd.yang.data+json Content-Type: application/vnd.yang.data+json
skipping to change at page 13, line 23 skipping to change at page 14, line 5
If the resource is updated, the server might respond: If the resource is updated, the server might respond:
HTTP/1.1 204 No Content HTTP/1.1 204 No Content
Date: Mon, 23 Apr 2012 17:49:30 GMT Date: Mon, 23 Apr 2012 17:49:30 GMT
Server: example-server Server: example-server
Last-Modified: Mon, 23 Apr 2012 17:49:30 GMT Last-Modified: Mon, 23 Apr 2012 17:49:30 GMT
ETag: b2788923da4c ETag: b2788923da4c
Refer to Section 3.6 for details on the PATCH operation. Refer to Section 3.6 for details on the PATCH operation.
1.2.2.5. Delete an Existing Data Resource 1.4.2.5. Delete an Existing Data Resource
To delete a resource such as the "album" resource, the client might To delete a resource such as the "album" resource, the client might
send: send:
DELETE /yang-api/datastore/jukebox/artist/1/album/ DELETE /yang-api/datastore/jukebox/artist/1/album/
Wasting%20Light HTTP/1.1 Wasting%20Light HTTP/1.1
Host: example.com Host: example.com
If the resource is deleted, the server might respond: If the resource is deleted, the server might respond:
HTTP/1.1 204 No Content HTTP/1.1 204 No Content
Date: Mon, 23 Apr 2012 17:49:40 GMT Date: Mon, 23 Apr 2012 17:49:40 GMT
Server: example-server Server: example-server
Refer to Section 3.7 for details on the DELETE operation. Refer to Section 3.7 for details on the DELETE operation.
1.2.2.6. Invoke a Data Model Specific Operation 1.4.2.6. Invoke a Data Model Specific Operation
To invoke a global operation, such as the "save-datastore" operation To invoke a data-model specific operation via an operation resource,
resource, the POST operation is used. A client might send a the POST operation is used. A client might send a "backup-datastore"
"save-datastore" request as follows: request as follows:
POST /yang-api/operations/save-datastore HTTP/1.1 POST /yang-api/operations/backup-datastore HTTP/1.1
Host: example.com Host: example.com
The server might respond: The server might respond:
HTTP/1.1 204 No Content HTTP/1.1 204 No Content
Date: Mon, 23 Apr 2012 17:50:00 GMT Date: Mon, 23 Apr 2012 17:50:00 GMT
Server: example-server Server: example-server
Refer to Section 3.9 for details on using the POST operation with Refer to Section 3.9 for details on using the POST operation with
operation resources. operation resources.
2. Framework 2. Framework
The YANG-API protocol defines a framework that can be used to The YANG-API protocol defines a framework that can be used to
implement a common API for configuration management. This section implement a common API for configuration management. This section
describes the components of the YANG-API framework. describes the components of the YANG-API framework.
2.1. Message Model 2.1. Message Model
The YANG-API protocol uses HTTP entities for messages. A single HTTP The YANG-API protocol uses HTTP entities for messages. A single HTTP
message corresponds to a single protocol operation in NETCONF. A message corresponds to a single protocol operation. A message can
message can perform a single task on a single resource, such as perform a single task on a single resource, such as retrieving a
retrieving a resource or editing a resource. It cannot be used to resource or editing a resource. It cannot be used to combine
combine multiple tasks. The client cannot provide multiple (possibly multiple tasks. The client cannot provide multiple (possibly
unrelated) edit operations within a single request, like the NETCONF unrelated) edit operations within a single request, like the NETCONF
<edit-config> protocol operation. <edit-config> protocol operation.
2.2. Resource Model 2.2. Resource Model
The YANG-API protocol operates on a hierarchy of resources, starting The YANG-API protocol operates on a hierarchy of resources, starting
with the top-level API resource itself. Each resource represents a with the top-level API resource itself. Each resource represents a
manageable component within the device. manageable component within the device.
A resource can be considered a collection of conceptual data and the A resource can be considered a collection of conceptual data and the
skipping to change at page 15, line 43 skipping to change at page 15, line 43
"Content-Type" header in the HTTP response message. A resource can "Content-Type" header in the HTTP response message. A resource can
contain zero or more fields and zero or more resources. A resource contain zero or more fields and zero or more resources. A resource
can be created and deleted independently of its parent resource, as can be created and deleted independently of its parent resource, as
long as the parent resource exist. long as the parent resource exist.
A field is a child node defined within a resource. A field can A field is a child node defined within a resource. A field can
contain zero or more fields and zero or more resources. A field contain zero or more fields and zero or more resources. A field
cannot be created and deleted independently of its parent resource. cannot be created and deleted independently of its parent resource.
All YANG-API resources and fields are defined in this document except All YANG-API resources and fields are defined in this document except
datastore contents and RPC operations. These resource types are datastore contents and protocol operations. These resource types are
defined with YANG data definition statements and the "rpc" statement. defined with YANG data definition statements and the "rpc" statement.
A default mapping is defined to differentiate sub-resources from A default mapping is defined to differentiate sub-resources from
fields within data resources. fields within data resources.
2.2.1. YANG-API Resource Types 2.2.1. YANG-API Resource Types
The YANG-API protocol defines some application specific media types The YANG-API protocol defines some application specific media types
to identify each of the available resource types. The following to identify each of the available resource types. The following
table summarizes the purpose of each resource. table summarizes the purpose of each resource.
+-------------+----------------------------------+ +-----------+--------------------------------+
| Resource | Media Type | | Resource | Media Type |
+-------------+----------------------------------+ +-----------+--------------------------------+
| API | application/vnd.yang.api | | API | application/vnd.yang.api |
| Datastore | application/vnd.yang.datastore | | Datastore | application/vnd.yang.datastore |
| Data | application/vnd.yang.data | | Data | application/vnd.yang.data |
| Operation | application/vnd.yang.operation | | Operation | application/vnd.yang.operation |
| Transaction | application/vnd.yang.transaction | +-----------+--------------------------------+
+-------------+----------------------------------+
YANG-API Media Types YANG-API Media Types
These resources are described in Section 5. These resources are described in Section 5.
2.2.2. Resource Discovery 2.2.2. Resource Discovery
A client SHOULD start by retrieving the top-level API resource, using A client SHOULD start by retrieving the top-level API resource, using
the entry point URI "/yang-api". the entry point URI "/yang-api".
skipping to change at page 16, line 48 skipping to change at page 16, line 47
A conceptual "unified datastore" is used to simplify resource A conceptual "unified datastore" is used to simplify resource
management for the client. The YANG-API datastore is a combination management for the client. The YANG-API datastore is a combination
of the running configuration and any non-configuration data supported of the running configuration and any non-configuration data supported
by the device. By default only configuration data is returned by a by the device. By default only configuration data is returned by a
GET operation on the datastore contents. GET operation on the datastore contents.
The underlying NETCONF datastores can be used to implement the The underlying NETCONF datastores can be used to implement the
unified datastore, but the server design is not limited to the exact unified datastore, but the server design is not limited to the exact
datastore procedures defined in NETCONF. datastore procedures defined in NETCONF.
Instead of a separate candidate configuration datastore to use as a The "candidate" and "startup" datastores are not visible in the YANG-
globally shared scratchpad to collect edits, an optional transaction API protocol. Transaction management and configuration persistence
mechanism is provided (see Section 2.4). are handled by the server and not controlled by the client.
Instead of a separate startup configuration datastore, a simplified
persistence model is used (see Section 2.3.4).
2.3.1. Content Model 2.3.1. Content Model
The YANG-API protocol operates on a conceptual datastore defined with The YANG-API protocol operates on a conceptual datastore defined with
the YANG data modeling language. The server lists each YANG module the YANG data modeling language. The server lists each YANG module
it supports in the "/yang-api/modules/module" field in the top-level it supports in the "/yang-api/modules/module" field in the top-level
API resource type, using the YANG module capability URI format API resource type, using the YANG module capability URI format
defined in RFC 6020. defined in RFC 6020.
The conceptual datastore contents and data-model-specific operations The conceptual datastore contents and data-model-specific operations
skipping to change at page 17, line 39 skipping to change at page 17, line 38
list resources to be inserted or moved in the same manner as NETCONF, list resources to be inserted or moved in the same manner as NETCONF,
and defined in YANG. and defined in YANG.
The server is not required to maintain system ordered data in any The server is not required to maintain system ordered data in any
particular persistent order. The server SHOULD maintain the same particular persistent order. The server SHOULD maintain the same
data ordering for system ordered data until the next reboot or data ordering for system ordered data until the next reboot or
termination of the server. termination of the server.
2.3.2. Editing Model 2.3.2. Editing Model
The YANG-API datastore editing model is compatible with the NETCONF The YANG-API datastore editing model is simple and direct, similar to
protocol but not exactly the same. the behavior of the ":writable-running" capability in NETCONF.
If the running configuration datastore is written directly, then each
change takes place right away. This can have a negative impact on
network behavior if multiple inter-related resources need to be
edited at once, in order to achieve the new desired network state.
To address this problem, an optional transaction mechanism is defined
(similar to the NETCONF :candidate capability) to allow multiple
edits to be collected and validated, before being applied all-or-
nothing to the running configuration datastore.
Private and shared transactions are supported. If the server uses a Each YANG-API edit of a datastore resource is activated upon
single shared datastore resource, or if multiple clients use the same successful completion of the transaction. It is an implementation-
private transaction, then it is often useful to know if the data specific matter how the server accomplishes a YANG-API edit request.
resources being edited have changed (relative to the resource For example, a server which only accepts edits through a candidate
versions the client thinks are on the server). datastore may internally edit this datastore and perform the "commit"
operation automatically.
This can be achieved in YANG-API using the edit collision detection Applications which need more control over the editing model might
mechanisms described in Section 2.3.2.2. If a collision is detected, consider using NETCONF instead of YANG-API.
then the client can retrieve the resource before proceeding with the
edit.
2.3.2.1. Edit Operation Discovery 2.3.2.1. Edit Operation Discovery
Sometimes a server does not implement every operation for every Sometimes a server does not implement every operation for every
resource. Sometimes data model requirements cause a node to resource. Sometimes data model requirements cause a node to
implement a subset of the edit operations. For example, a server may implement a subset of the edit operations. For example, a server may
not allow modification of a particular configuration data node after not allow modification of a particular configuration data node after
the parent resource has been created. the parent resource has been created.
The OPTIONS operation can be used to identify which operations are The OPTIONS operation can be used to identify which operations are
skipping to change at page 19, line 14 skipping to change at page 19, line 4
last-changed timestamp. The client has previously retrieved the last-changed timestamp. The client has previously retrieved the
"Last-Modified" header and has some value cached to provide in the "Last-Modified" header and has some value cached to provide in the
following request to replace a list entry with key value "11": following request to replace a list entry with key value "11":
PATCH /yang-api/datastore/jukebox/artist/1/album/ PATCH /yang-api/datastore/jukebox/artist/1/album/
Wasting%20Light/year HTTP/1.1 Wasting%20Light/year HTTP/1.1
Host: example.com Host: example.com
Accept: application/vnd.yang.data+json Accept: application/vnd.yang.data+json
If-Unmodified-Since: Mon, 23 Apr 2012 17:01:00 GMT If-Unmodified-Since: Mon, 23 Apr 2012 17:01:00 GMT
Content-Type: application/vnd.yang.data+json Content-Type: application/vnd.yang.data+json
{ "year" : "2011" } { "year" : "2011" }
In this example the datastore resource has changed since the time In this example the datastore resource has changed since the time
specified in the "If-Unmodified-Since" header. The server might specified in the "If-Unmodified-Since" header. The server might
respond: respond:
HTTP/1.1 304 Not Modified HTTP/1.1 304 Not Modified
Date: Mon, 23 Apr 2012 19:01:00 GMT Date: Mon, 23 Apr 2012 19:01:00 GMT
Server: example-server Server: example-server
Last-Modified: Mon, 23 Apr 2012 17:45:00 GMT Last-Modified: Mon, 23 Apr 2012 17:45:00 GMT
ETag: b34aed893a4c ETag: b34aed893a4c
2.3.3. Locking Model 2.3.3. Locking Model
Datastore locking is needed in order to allow a client to make Datastore locking is not provided by YANG-API. An application that
several changes to the running configuration datastore contents in needs to make several changes to the running configuration datastore
sequence, without disturbance from other clients. contents in sequence, without disturbance from other clients might
consider using the NETCONF protocol instead of YANG-API.
The "lock-datastore" and "unlock-datastore" operations MUST be
supported by the server. These correspond to the global locks
defined in NETCONF. Only the running configuration datastore can be
locked and unlocked in this manner. If the datastore is locked, then
direct edits and transaction commits by other clients will fail.
The editing model allows for concurrent transactions to occur without
locking, using the transaction "update" operation. This is similar
to the "discard-changes" operation, except that the running
configuration datastore is merged into the current transaction
datastore (instead of replacing the contents). If the "update"
cannot be done, a conflict error report is generated so the client
can manually resolve the differences.
A client can request exclusive write access when a transaction
resource is created. This is comparable to a global lock on the
candidate configuration datastore if the server "transaction-model"
capability field is set to "shared". In this case, the creation of
the new transaction resource will fail if another exclusive
transaction already exists.
There is no partial datastore locking (i.e., per-resource or per YANG
data node) at this time. Explicit partial locks are difficult to use
and easy to misuse. Transactions are easier for a client to use, and
allow more server design freedom as well.
2.3.4. Persistence Model 2.3.4. Persistence Model
A client must be aware of how the server saves configuration data to Each YANG-API edit of a datastore resource is saved to non-volatile
non-volatile storage, so the server advertises its persistence model storage in an implementation-specific matter by the server. There is
(either "automatic" or "manual"). no guarantee that configuration changes are saved immediately, or
that the saved configuration is always a mirror of the running
If manual persistence of the running configuration datastore is configuration.
required, then the "persist" operation MUST be supported by the
server and MUST be used by the client to save the running
configuration datastore contents to non-volatile storage.
If automatic persistence of the running configuration datastore is Applications which need more control over the persistence model might
supported by the server, then the non-volatile storage of consider using NETCONF instead of YANG-API.
configuration changes is handled automatically by the server, and the
"persist" operation MUST NOT be supported by the server.
2.3.5. Defaults Model 2.3.5. Defaults Model
NETCONF has a rather complex defaults handling model for leafs. NETCONF has a rather complex defaults handling model for leafs.
YANG-API attempts to avoid this complexity by restricting the YANG-API attempts to avoid this complexity by restricting the
operations that can be applied to a resource and fields within that operations that can be applied to a resource and fields within that
resource. resource.
The GET method returns only nodes that exist, which will be The GET method returns only nodes that exist, which will be
determined by the server. There is no mechanism for the client to determined by the server. There is no mechanism for the client to
ask the server for the default values that would be used for any ask the server for the default values that would be used for any
nodes not present, but some default value is in use by the server. nodes not present, but some default value is in use by the server.
(There is no
retrieval mode like "with-defaults=report-all" in NETCONF.)
If a leaf definition has a default value, and the leaf has not been If a leaf definition has a default value, and the leaf has not been
given a value yet, the server SHOULD NOT return any value for the given a value yet, the server SHOULD NOT return any value for the
leaf in the response for a GET operation. leaf in the response for a GET operation.
2.4. Transaction Model Applications which need more control over the defaults model might
consider using NETCONF instead of YANG-API.
The "/yang-api/transaction" resource will be present if the server
supports transactions. If so, the server MUST support at least one
transaction at a time and MAY support multiple concurrent
transactions, either by one client or multiple clients.
The "/yang-api/capabilities/transaction-model" field in the top-level
API resource identifies which type of transactions the server
supports, either "none", "shared", or "private". If shared, then all
clients are sharing the same "/yang-api/transaction/<id>/datastore"
resource. If "private" then each instance of a "/yang-api/
transaction/<id>/datastore" resource is independent of each another.
There are a small number of operations supported for a transaction
resource.
o commit: attempt to commit the transaction.
o discard-changes: replace the contents of the transaction datastore
to the contents of the running configuration datastore.
o update: merge the contents of the running configuration datastore 2.4. Transaction Model
into the transaction datastore.
o validate: Run commit validation tests against the running The YANG-API protocol does not provide a complex transaction model
configuration datastore contents, according to section 8.3.3 of that allows for multiple protocol operations, or even operations on
[RFC6020]. multiple resources in one protocol operation. A very simple "one
operation one one resource" per transaction model is used instead.
Refer to Section 5.5.4 for more details on these operations. Applications which need more control over the transaction model might
consider using NETCONF instead of YANG-API.
2.5. Extensibility Model 2.5. Extensibility Model
The YANG-API protocol is designed to be extensible for datastore The YANG-API protocol is designed to be extensible for datastore
content and data-model specific RPC operations. New RPC operations content and data-model specific protocol operations. New protocol
can be added without changing the entry point if they are optional operations can be added without changing the entry point if they are
and do not alter any existing operations. optional and do not alter any existing operations.
Separate namespaces for each YANG module are used. Content encoded Separate namespaces for each YANG module are used. Content encoded
in XML will indicate the module using the "namespace" URI value in in XML will indicate the module using the "namespace" URI value in
the YANG module. Content encoded in JSON will indicate the module the YANG module. Content encoded in JSON will indicate the module
using the module name specified in the YANG module. JSON encoding using the module name specified in the YANG module. JSON encoding
rules for module namespaces are specified in [I-D.lhotka-yang-json]. rules for module namespaces are specified in
[I-D.lhotka-netmod-json].
2.6. Versioning Model 2.6. Versioning Model
The version of a resource instance is identified with an entity tag, The version of a resource instance is identified with an entity tag,
as defined by HTTP. The version identifiers in this section apply to as defined by HTTP. The version identifiers in this section apply to
the version of the schema definition of a resource. There are two the version of the schema definition of a resource. There are two
types of schema versioning information used in the YANG-API protocol: types of schema versioning information used in the YANG-API protocol:
o the YANG-API protocol version o the YANG-API protocol version
skipping to change at page 28, line 16 skipping to change at page 26, line 16
The POST operation is sent by the client for various reasons. The The POST operation is sent by the client for various reasons. The
HTTP POST method is used for this purpose. The request MUST contain HTTP POST method is used for this purpose. The request MUST contain
a request URI that contains a target resource that identifies one of a request URI that contains a target resource that identifies one of
the following resource types: the following resource types:
+-------------+--------------------------------------+ +-------------+--------------------------------------+
| Type | Description | | Type | Description |
+-------------+--------------------------------------+ +-------------+--------------------------------------+
| Data | Create a configuration data resource | | Data | Create a configuration data resource |
| Operation | Invoke RPC operation | | Operation | Invoke protocol operation |
| Transaction | Create a new transaction | | Transaction | Create a new transaction |
+-------------+--------------------------------------+ +-------------+--------------------------------------+
Resource Types that Support POST Resource Types that Support POST
The following query parameters are supported by the POST operation: The following query parameters are supported by the POST operation:
+--------+---------+-----------------------------------------+ +--------+---------+-----------------------------------------+
| Name | Section | Description | | Name | Section | Description |
+--------+---------+-----------------------------------------+ +--------+---------+-----------------------------------------+
skipping to change at page 34, line 36 skipping to change at page 32, line 36
the context node. the context node.
It is supported for all resource types except operation resources. It is supported for all resource types except operation resources.
The contents are encoded according to the "api-select" rule defined The contents are encoded according to the "api-select" rule defined
in Section 5.3.1. This parameter is only allowed for GET and HEAD in Section 5.3.1. This parameter is only allowed for GET and HEAD
operations. operations.
[FIXME: the syntax of the select string is still TBD; XPath, schema- [FIXME: the syntax of the select string is still TBD; XPath, schema-
identifier, regular expressions, something else] identifier, regular expressions, something else]
Refer to Section 1.2.2 for example request messages using the Refer to Section 1.4.2 for example request messages using the
"select" parameter. "select" parameter.
3.9. RPC Operations 3.9. Protocol Operations
The YANG-API also allows RPC operations to be invoked using the POST
method. The media type "vnd.yang.operation+xml" or
"vnd.yang.operation+json" MUST be used in the "Content-Type" field in
the message header.
The following datastore specific operations are defined:
+------------------+------------------------------------------------+
| Operation | Description |
+------------------+------------------------------------------------+
| lock-datastore | Lock the /yang-api/datastore resource for |
| | writing |
| save-datastore | Save the /yang-api/datastore resource to |
| | NV-storage |
| unlock-datastore | Unlock the /yang-api/datastore resource |
+------------------+------------------------------------------------+
YANG-API Datastore Operations
Refer to Section 5.2 for details on these operations.
The following transaction specific operations are defined:
+-----------------+-------------------------------------------------+
| Operation | Description |
+-----------------+-------------------------------------------------+
| commit | Commit the transaction to the running config |
| discard-changes | replace transaction data with current running |
| | config |
| update | merge current running config into transaction |
| | data |
| validate | validate transaction datastore |
+-----------------+-------------------------------------------------+
YANG-API Transaction Operations
Refer to Section 5.5 for details on these operations.
3.9.1. Data Model Specific Operations The YANG-API also allows data-model specific protocol operations to
be invoked using the POST method. The media type
"vnd.yang.operation+xml" or "vnd.yang.operation+json" MUST be used in
the "Content-Type" field in the message header.
Data model specific operations are supported. The syntax and Data model specific operations are supported. The syntax and
semantics of these operations exactly correspond to the YANG rpc semantics of these operations exactly correspond to the YANG "rpc"
statement definition for the operation. statement definition for the operation.
Any input for a RPC operation is encoded in an element called Any input for a protocol operation is encoded in an element called
"input", which corresponds to the <input> element in a NETCONF "input", which corresponds to the <input> element in a NETCONF
message. The child nodes of the "input" element are encoded message. The child nodes of the "input" element are encoded
according to the data definition statements in the input section of according to the data definition statements in the input section of
the rpc statement. the "rpc" statement.
Any output for a RPC operation is encoded in an element called Any output for a protocol operation is encoded in an element called
"output", which corresponds to the <rpc-reply> element in a NETCONF "output", which corresponds to the <rpc-reply> element in a NETCONF
message. The child nodes of the "output" element are encoded message. The child nodes of the "output" element are encoded
according to the data definition statements in the output section of according to the data definition statements in the output section of
the rpc statement. the "rpc" statement.
4. Messages 4. Messages
This section describes the messages that are used in the YANG-API This section describes the messages that are used in the YANG-API
protocol. protocol.
4.1. Request URI Structure 4.1. Request URI Structure
Resources are represented with URIs following the structure for Resources are represented with URIs following the structure for
generic URIs in [RFC3986]. generic URIs in [RFC3986].
skipping to change at page 38, line 32 skipping to change at page 36, line 32
YANG-API messages are encoded in HTTP according to RFC 2616. The YANG-API messages are encoded in HTTP according to RFC 2616. The
"utf-8" character set is used for all messages. YANG-API message "utf-8" character set is used for all messages. YANG-API message
content is sent in the HTTP message body. content is sent in the HTTP message body.
Content is encoded in either JSON or XML format. Content is encoded in either JSON or XML format.
XML encoding rules for data nodes are defined in [RFC6020]. The same XML encoding rules for data nodes are defined in [RFC6020]. The same
encoding rules are used for all XML content. XML attributes are not encoding rules are used for all XML content. XML attributes are not
used and will be ignored if present in an XML-encoded message. used and will be ignored if present in an XML-encoded message.
JSON encoding rules are defined in [I-D.lhotka-yang-json]. Special JSON encoding rules are defined in [I-D.lhotka-netmod-json]. Special
encoding rules are needed to handle multiple module namespaces and encoding rules are needed to handle multiple module namespaces and
provide consistent data type processing. provide consistent data type processing.
Request input content encoding format is identified with the Content- Request input content encoding format is identified with the Content-
Type header. This field MUST be present if message input is sent by Type header. This field MUST be present if message input is sent by
the client. the client.
Response output content encoding format is identified with the Accept Response output content encoding format is identified with the Accept
header, the "format" query parameter, or if neither is specified, the header, the "format" query parameter, or if neither is specified, the
request input encoding format is used. If there was no request request input encoding format is used. If there was no request
skipping to change at page 40, line 22 skipping to change at page 38, line 22
The API resource contains the state and access points for the YANG- The API resource contains the state and access points for the YANG-
API features. API features.
It is the top-level resource and has the media type "application/ It is the top-level resource and has the media type "application/
vnd.yang.api+xml" or "application/vnd.yang.api+json". It is vnd.yang.api+xml" or "application/vnd.yang.api+json". It is
accessible through the well-known URI "/yang-api". accessible through the well-known URI "/yang-api".
This resource has the following fields: This resource has the following fields:
+--------------+--------------------------------+ +------------+--------------------------------+
| Field Name | Description | | Field Name | Description |
+--------------+--------------------------------+ +------------+--------------------------------+
| capabilities | Server capabilities | | datastore | Link to "datastore" resource |
| datastore | Link to "datastore" resource | | modules | YANG module capability URIs |
| operations | Global operations | | operations | Data-model specific operations |
| modules | YANG modules | +------------+--------------------------------+
| transaction | Link to "transaction" resource |
+--------------+--------------------------------+
YANG-API Resource Fields YANG-API Resource Fields
5.1.1. /yang-api/capabilities 5.1.1. /yang-api/datastore
This mandatory field represents the YANG-API server capabilities.
The child nodes are read-only fields that MUST NOT change while the
server is running, but MAY change after a reboot.
Example:
To retrieve just the YANG-API capabilities, the client might send the
following request:
GET /yang-api?select=capabilities HTTP/1.1
Host: example.com
The server might respond:
HTTP/1.1 200 OK
Date: Mon, 23 Apr 2012 17:10:00 GMT
Server: example-server
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/vnd.yang.api+json
{
"yang-api": {
"capabilities": {
"edit-model": "transaction",
"persist-model": "manual",
"transaction-model": "private"
}
}
}
5.1.1.1. /yang-api/capabilities/edit-model
The "edit-model" capability field is used to identify the editing
model used by the server. There are 4 supported models:
o none: A server within a constrained device MAY choose to provide a
read-only implementation, in which case no editing model is
supported.
o direct: A device MAY allow the running configuration datastore to
only be modified directly, and therefore will not support
transactions.
o transaction: A device SHOULD support the transaction mechanism
defined in this document. Datastore edits are collected in the
transaction datastore and applied to the running configuration
datastore with the "commit" operation.
o both: A device MAY support both the direct and transaction editing
models, by allowing direct editing operations on the datastore and
supporting the transaction mechanism.
The server SHOULD support 1 of the 2 datastore editing models, and
MAY support both datastore editing models. If both are supported,
then the client can decide which editing model it prefers.
This field is encoded with the rules for a "bits" data type, using
the following leaf definition:
leaf edit-model {
config false;
type bits {
bit direct {
description
"Direct writing to the datastore resource is allowed.";
}
bit transaction {
description
"Writing to the datastore via transactions is allowed.";
}
}
}
There is no default. The server MUST set zero, one, or both of these
bits in the "edit-model" capability field.
5.1.1.2. /yang-api/capabilities/persist-model
The "persist-model" capability field is used to identify the
persistence model used by the server. There are two supported
models:
o automatic: The server will automatically save the running
configuration datastore contents to non-volatile storage.
o manual: The client must manually save the running configuration
datastore contents to non-volatile storage.
This field is encoded with the rules for an "enumeration" data type,
using the following leaf definition:
leaf persist-model {
config false;
type enumeration {
enum automatic {
description
"The server will automatically save the
running configuration";
}
enum manual {
description
"The client must manually save the running
configuration";
}
}
}
There is no default. The server MUST set one enumeration value in
the "persist-model" capability field.
5.1.1.3. /yang-api/capabilities/transaction-model
The "transaction-model" capability field is used to identify the
transaction model used by the server. There are 3 supported models:
o none: The server does not support transactions.
o shared: All clients are sharing the same conceptual transaction
datastore (similar to NETCONF :candidate capability).
o private: Each transaction datastore resource is independent of one
another.
This field is encoded with the rules for an "enumeration" data type,
using the following leaf definition:
leaf transaction-model {
config false;
type enumeration {
enum none {
description
"The server does not support transactions.";
}
enum shared {
description
"The server supports a shared transaction datastore
resource.";
}
enum private {
description
"The server supports a private transaction datastore
resource.";
}
}
}
There is no default. The server MUST set one enumeration value in
the "transaction-model" capability field.
5.1.2. /yang-api/datastore
This mandatory resource represents the running configuration This mandatory resource represents the running configuration
datastore and any non-configuration data available. It may be datastore and any non-configuration data available. It may be
retrieved and edited directly or indirectly (via transactions). It retrieved and edited directly. It cannot be created or deleted by
cannot be created or deleted by the client. This resource type is the client. This resource type is defined in Section 5.2.
defined in Section 5.2.
5.1.3. /yang-api/operations
This optional field provides access to the global datastore and data-
model specific RPC operations supported by the server. The datastore
operation resources will be available depending on the server
capabilities. If the server does not support any global operations,
then this field SHOULD NOT not be present.
There are 3 global operations defined by YANG-API.
o lock-datastore
o save-datastore
o unlock-datastore
Any data-model specific global operations derived from YANG modules
supported by the server will also be available through child node
resources within the "operations" field. The YANG-API defined global
operations are described in this section.
5.1.3.1. /yang-api/operations/lock-datastore
The "lock-datastore" operation resource is used to lock the datastore
resource represented by the URI "/yang-api/datastore". It behaves
exactly the same as the NETCONF <lock> operation on the running
configuration datastore.
If the operation succeeds, a "204 No Content" value in the
"Status-Line" is sent in the response. If the operation fails, the
appropriate error code is set according to the rules in Section 6,
and the error report is sent in the response, according to the format
defined in Section 6.1.
The "lock-datastore" operation does not take any parameters. The
YANG "rpc" statement definition for this operation is defined in
Section 8.
Example:
The client might request a lock on the running configuration
datastore as follows:
POST /yang-api/operations/lock-datastore HTTP/1.1
Host: example.com
If the operation succeeds the server might respond:
HTTP/1.1 204 No Content
Date: Mon, 23 Apr 2012 17:03:00 GMT
Server: example-server
If the operation fails the server might respond:
HTTP/1.1 204 No Content
Date: Mon, 23 Apr 2012 17:03:00 GMT
Server: example-server
5.1.3.2. /yang-api/operations/save-datastore
The "save-datastore" operation resource is used to save the datastore
resource represented by the URI "/yang-api/datastore" to non-volatile
storage. It behaves exactly the same as the NETCONF <copy-config>
operation when used to copy the running configuration datastore to
the startup configuration datastore.
If the operation succeeds, a "204 No Content" value in the
"Status-Line" is sent in the response. If the operation fails, the
appropriate error code is set according to the rules in Section 6,
and the error report is sent in the response, according to the format
defined in Section 6.1.
The "save-datastore" operation does not take any parameters. The
YANG "rpc" statement definition for this operation is defined in
Section 8.
Example:
The client might request that the running configuration datastore be
saved in non-volatile storage as follows:
POST /yang-api/operations/save-datastore HTTP/1.1
Host: example.com
If the operation succeeds the server might respond:
HTTP/1.1 204 No Content
Date: Mon, 23 Apr 2012 17:03:00 GMT
Server: example-server
If the operation fails the server might respond:
HTTP/1.1 204 No Content
Date: Mon, 23 Apr 2012 17:03:00 GMT
Server: example-server
5.1.3.3. /yang-api/operations/unlock-datastore
The "unlock-datastore" operation resource is used to unlock the
datastore resource represented by the URI "/yang-api/datastore". It
behaves exactly the same as the NETCONF <unlock> operation on the
running configuration datastore.
If the operation succeeds, a "204 No Content" value in the
"Status-Line" is sent in the response. If the operation fails, the
appropriate error code is set according to the rules in Section 6,
and the error report is sent in the response, according to the format
defined in Section 6.1.
The "unlock-datastore" operation does not take any parameters. The
YANG "rpc" statement definition for this operation is defined in
Section 8.
Example:
The client might release a lock on the running configuration
datastore as follows:
POST /yang-api/operations/unlock-datastore HTTP/1.1
Host: example.com
If the operation succeeds the server might respond:
HTTP/1.1 204 No Content
Date: Mon, 23 Apr 2012 17:03:00 GMT
Server: example-server
If the operation fails the server might respond:
HTTP/1.1 204 No Content
Date: Mon, 23 Apr 2012 17:03:00 GMT
Server: example-server
5.1.4. /yang-api/modules 5.1.2. /yang-api/modules
This mandatory field contains the identifiers for the YANG data model This mandatory field contains the identifiers for the YANG data model
modules supported by the server. There MUST be exactly one instance modules supported by the server. There MUST be exactly one instance
of this field. of this field.
The server MUST maintain a last-modified timestamp for this field, The server MUST maintain a last-modified timestamp for this field,
and return the "Last-Modified" header when this field is retrieved and return the "Last-Modified" header when this field is retrieved
with the GET or HEAD methods. with the GET or HEAD methods.
5.1.4.1. /yang-api/modules/module 5.1.3. /yang-api/operations
This optional field provides access to the data-model specific
protocol operations supported by the server. The server MAY omit
this field if no data-model specific operations are advertised.
Any data-model specific operations defined in the YANG modules
advertised by the server SHOULD be available as child nodes of this
field.
5.1.3.1. /yang-api/modules/module
This mandatory field contains one URI string for each YANG data model This mandatory field contains one URI string for each YANG data model
module supported by the server. There MUST be an instance of this module supported by the server. There MUST be an instance of this
field for every YANG module that is accessible via an operation field for every YANG module that is accessible via an operation
resource or a data resource. resource or a data resource.
The server MAY maintain a last-modified timestamp for each instance The server MAY maintain a last-modified timestamp for each instance
of this resource, and return the "Last-Modified" header when this of this resource, and return the "Last-Modified" header when this
resource is retrieved with the GET or HEAD methods. If not supported resource is retrieved with the GET or HEAD methods. If not supported
then the timestamp for the parent "modules" field MUST NOT be used then the timestamp for the parent "modules" field MUST NOT be used
instead. instead.
The contents of this field are encoded with the "uri" derived type The contents of this field are encoded with the "uri" derived type
from the "ietf-iana-types" modules in [RFC6021]. from the "ietf-iana-types" modules in [RFC6021].
There are additional encoding requirements for this field. The URI There are additional encoding requirements for this field. The URI
MUST follow the YANG module capability URI formatting defined in MUST follow the YANG module capability URI formatting defined in
section 5.6.4 of [RFC6020]. section 5.6.4 of [RFC6020].
5.1.4.2. Retrieval Example 5.1.3.2. Retrieval Example
In this example the client is retrieving the modules field from the In this example the client is retrieving the modules field from the
server in the default JSON format: server in the default JSON format:
GET /yang-api?select=modules HTTP/1.1 GET /yang-api?select=modules HTTP/1.1
Host: example.com Host: example.com
Accept: application/vnd.yang.api+json Accept: application/vnd.yang.api+json
The server might respond as follows. Note that the content below is The server might respond as follows. Note that the content below is
split across multiple lines for display purposes only: split across multiple lines for display purposes only:
skipping to change at page 48, line 26 skipping to change at page 40, line 26
"module": [ "module": [
"example.com?module=foo&revision=2012-01-02", "example.com?module=foo&revision=2012-01-02",
"example.com?module=bar&revision=2011-10-10" "example.com?module=bar&revision=2011-10-10"
"example.com?module=itf&revision=2011-10-10 "example.com?module=itf&revision=2011-10-10
&feature=restore" &feature=restore"
] ]
} }
} }
} }
5.1.5. /yang-api/transaction 5.1.4. /yang-api/version
This optional resource will be supported if the server implements
transactions, identified by the "/yang-api/capabilities/edit-model"
field in the API resource. It is used to allow one or more
individual edits to be applied (all-or-nothing) to the running
configuration datastore, and to facilitate concurrent editing
transactions with a mechanism to update the transaction datastore
contents with the latest running configuration datastore contents.
This resource is defined in Section 5.5.
5.1.6. /yang-api/version
This mandatory field identifies the specific version of the YANG-API This mandatory field identifies the specific version of the YANG-API
protocol implemented by the server. protocol implemented by the server.
The same server-wide response MUST be returned each time this field The same server-wide response MUST be returned each time this field
is retrieved. It is assigned by the server when the server is is retrieved. It is assigned by the server when the server is
started. The server MUST return the value "1.0" for this version of started. The server MUST return the value "1.0" for this version of
the YANG-API protocol. the YANG-API protocol.
This field is encoded with the rules for an "enumeration" data type, This field is encoded with the rules for an "enumeration" data type,
skipping to change at page 52, line 7 skipping to change at page 43, line 43
o The "/" character MUST be URL-encoded (i.e., "%2F"). o The "/" character MUST be URL-encoded (i.e., "%2F").
o All whitespace MUST be URL-encoded. o All whitespace MUST be URL-encoded.
o A "null" value is not allowed since the "empty" data type is not o A "null" value is not allowed since the "empty" data type is not
allowed for key leafs. allowed for key leafs.
o The XML encoding is defined in [RFC6020]. o The XML encoding is defined in [RFC6020].
o The JSON encoding is defined in [I-D.lhotka-yang-json]. o The JSON encoding is defined in [I-D.lhotka-netmod-json].
o The entire "key-value" MUST be properly URL-encoded, according to o The entire "key-value" MUST be properly URL-encoded, according to
the rules defined in [RFC3986]. the rules defined in [RFC3986].
Notifications are not supported by YANG-API because they are not
supported by HTTP. YANG notification statements are ignored by a
YANG-API server.
Examples: Examples:
/yang-api/datastore/jukebox/library/artist/17&select=name /yang-api/datastore/jukebox/library/artist/17&select=name
/yang-api/datastore/newlist/17&select=nextlist/22/44/myleaf /yang-api/datastore/newlist/17&select=nextlist/22/44/myleaf
/yang-api/datastore/somelist/fred%20and%20wilma /yang-api/datastore/somelist/fred%20and%20wilma
/yang-api/datastore/somelist/fred%20and%20wilma/address /yang-api/datastore/somelist/fred%20and%20wilma/address
skipping to change at page 53, line 41 skipping to change at page 45, line 35
the server selected, so the client does not need to provide all the the server selected, so the client does not need to provide all the
key leaf values. key leaf values.
It is useful to identify in the YANG data model module which key It is useful to identify in the YANG data model module which key
leafs are optional to provide, and which are not. The YANG extension leafs are optional to provide, and which are not. The YANG extension
statement "optional-key" is provided to indicate that the leaf statement "optional-key" is provided to indicate that the leaf
definition represents an optional key. definition represents an optional key.
The client MAY provide a value for a key leaf in a POST operation. The client MAY provide a value for a key leaf in a POST operation.
Refer to Section 8 for details on the "optional-key" extension. Refer to Section 8 for details on the "optional-key" extension.
Refer to Section 12 for usage examples of this YANG extension Refer to Section 13 for usage examples of this YANG extension
statement. statement.
5.3.4. Data Resource Retrieval 5.3.4. Data Resource Retrieval
There are four types of filtering for retrieval of data resources. There are four types of filtering for retrieval of data resources.
This section defines each mode. This section defines each mode.
5.3.4.1. Conditional Retrieval 5.3.4.1. Conditional Retrieval
The HTTP headers (such as "If-Modified-Since" and "If-Match") can by The HTTP headers (such as "If-Modified-Since" and "If-Match") can by
skipping to change at page 55, line 45 skipping to change at page 47, line 42
The "select" query parameter is used to specify a filter that should The "select" query parameter is used to specify a filter that should
be applied to the target resource to request a subset of all possible be applied to the target resource to request a subset of all possible
descendant nodes within the target resource. descendant nodes within the target resource.
The format of the "select" parameter string is defined in The format of the "select" parameter string is defined in
Section 3.8.6. The set of nodes selected by the filter expression is Section 3.8.6. The set of nodes selected by the filter expression is
applied to each context node identified by the target resource. applied to each context node identified by the target resource.
5.4. Operation Resource 5.4. Operation Resource
An operation resource represents an RPC operation defined with the An operation resource represents an protocol operation defined with
YANG "rpc" statement. the YANG "rpc" statement.
All operation resources share the same module namespace as any top- All operation resources share the same module namespace as any top-
level data resources, so the name of an operation resource cannot level data resources, so the name of an operation resource cannot
conflict with the name of a top-level data resource defined within conflict with the name of a top-level data resource defined within
the same module. the same module.
If 2 different YANG modules define the same "rpc" identifier, then If 2 different YANG modules define the same "rpc" identifier, then
the module name MUST be used in the request URI. For example, if the module name MUST be used in the request URI. For example, if
"module-A" and "module-B" both defined a "reset" operation, then "module-A" and "module-B" both defined a "reset" operation, then
invoking the operation from "module-A" would be requested as follows: invoking the operation from "module-A" would be requested as follows:
POST /yang-api/operations/module-A:reset HTTP/1.1 POST /yang-api/operations/module-A:reset HTTP/1.1
Server example.com Server example.com
Any usage of an operation resource from the same module, with the Any usage of an operation resource from the same module, with the
same name, refers to the same "rpc" statement definition. This same name, refers to the same "rpc" statement definition. This
behavior can be used to design RPC operations that perform the same behavior can be used to design protocol operations that perform the
general function on different resource types. same general function on different resource types.
If the "rpc" statement has an "input" section, then a message body If the "rpc" statement has an "input" section, then a message body
MAY be sent by the client in the request, otherwise the request MAY be sent by the client in the request, otherwise the request
message MUST NOT include a message body. If the "rpc" statement has message MUST NOT include a message body. If the "rpc" statement has
an "output" section, then a message body MAY be sent by the server in an "output" section, then a message body MAY be sent by the server in
the response. Otherwise the server MUST NOT include a message body the response. Otherwise the server MUST NOT include a message body
in the response message, and MUST send a "204 No Content" Status-Line in the response message, and MUST send a "204 No Content" Status-Line
instead. instead.
5.4.1. Encoding Operation Input Parameters 5.4.1. Encoding Operation Input Parameters
skipping to change at page 58, line 24 skipping to change at page 51, line 5
"language" : "en-US" "language" : "en-US"
} }
} }
5.4.3. Identifying YANG-defined Operation Resources 5.4.3. Identifying YANG-defined Operation Resources
The operation resources used in YANG-API are defined with YANG "rpc" The operation resources used in YANG-API are defined with YANG "rpc"
statements. All "rpc" statements within a YANG module that are statements. All "rpc" statements within a YANG module that are
supported by the server are available as operation resources. supported by the server are available as operation resources.
5.5. Transaction Resource
The "transaction" resource type is used to construct a set of one or
more edit operations on data resources within a "scratchpad"
datastore resource. The transaction can be committed when the client
decides the data resource edits are complete. The transaction can
also be reverted and updated, as described later in this section.
This resource type will only be supported if the "edit-model"
capabilities field in the API resource includes the value
"transaction". If transactions are supported, then the server will
allow the client to create, use, and delete transaction resources.
The POST operation is used to create a new transaction resource. The
DELETE operation is used to cleanup and delete an existing
transaction resource. The PUT and PATCH operations are not supported
for this resource type.
The media type for the transaction resource type is either
"application/vnd.yang.transaction+xml" or "application/
vnd.yang.transaction+json".
The procedures for editing the transaction datastore contents are the
same as those for editing the running configuration datastore except
the changes do not take effect right away and the datastore integrity
validation tests are not done until the transaction is committed to
running configuration datastore.
The following steps are typically followed to use transaction
resources:
o create a transaction resource using the URI "/yang-api/
transaction".
o the server will allocate a new transaction and return its resource
ID.
o add/alter/delete data resources within the scratchpad datastore
o commit the transaction to the running configuration datastore.
o delete the transaction resource
5.5.1. Creating a Transaction Resource
In order to reduce the complexity of query parameters and allow
easier extensibility of transaction resource creation, the
configuration parameters for the transaction are sent in the request
message for the POST operation.
The only parameter at this time is the "exclusive-mode" parameter,
which is used by the client to request that no other transactions or
direct edits are allowed to alter the running configuration datastore
while the exclusive mode transaction resource exists. An exclusive
mode transaction if the server transaction-model is "shared" is
conceptually equivalent in NETCONF to global locks on both the
"candidate" and "running" datastores.
The following YANG leaf definition is used for the "exclusive-mode"
parameter, for encoding purposes:
leaf exclusive-mode {
type boolean;
default false;
description "Exclusive transaction mode";
}
When a transaction resource is created by the client, the server will
generate an opaque string to identify the transaction. This
transaction ID will be used by the server in the resource ID for the
new transaction.
If the server uses a shared transaction model, then the transaction
ID MAY be the same for multiple transaction resources. Otherwise the
server SHOULD use a unique identifier for each transaction resource.
The server does not ensure exclusive access to a particular
transaction. The access control mechanisms for sharing transactions
is out of scope for this document.
After a transaction has been successfully created, it can be accessed
via the "Location" header returned in the response message.
Example:
The following message shows an exclusive transaction resource
request. The client might send:
POST /yang-api/transaction HTTP/1.1
Host: example.com
Content-Type: application/vnd.yang.transaction+json
{
"transaction" : {
"exclusive-mode" : true
}
}
The server might reply:
HTTP/1.1 201 Created
Date: Mon, 23 Apr 2012 17:01:00 GMT
Server: example-server
Location: http://example.com/yang-api/transaction/12345
Last-Modified: Mon, 23 Apr 2012 19:48:00 GMT
ETag: b38830de24c
5.5.2. Editing a Transaction Datastore
When a transaction resource is created, the server will create a
child datastore resource, which is a conceptual scratchpad for
collecting edits to later be applied all at once to the running
configuration datastore. The initial contents of this datastore are
the contents of the running configuration datastore at the time the
transaction is created.
After a transaction has been successfully created, it can be accessed
by using the previously retrieved "Location" header value in the
request URI of new request messages. This datastore resource is a
child node of the resource ID node, identified by a URI.
For example, the "path" component of a request URI for a datastore
resource (for transaction ID "12345") would be:
"/yang-api/transaction/12345/datastore"
The client can add, edit, or delete the data resources within the
transaction datastore. Refer to Section 5.3 for details on editing
data resources.
Example:
The following message shows the creation of a new "artist" resource
within the "jukebox" resource. The request URI is split across lines
for display purposes only.
The client might send:
POST /yang-api/transaction/12345/datastore/jukebox/
library/artist HTTP/1.1
Host: example.com
Content-Type: application/vnd.yang.data+json
{
"artist" : {
"name" : "Miles Davis"
}
}
The server might reply as follows. The "Location" header is split
across lines for display purposes only.
HTTP/1.1 201 Created
Date: Mon, 24 Apr 2012 11:01:00 GMT
Server: example-server
Location: http://example.com/yang-api/transaction/
12345/datastore/jukebox/library/artist/2
Last-Modified: Mon, 24 Apr 2012 11:01:00 GMT
ETag: b38830de24c
5.5.3. Deleting a Transaction Resource
Once a client is finished with a transaction resource, it SHOULD be
deleted by the client. A transaction resource is not deleted when a
commit is completed. The DELETE operation is used to terminate the
transaction, and discard the transaction database and all its data
resource contents.
Example:
The following message shows the deletion of an existing transaction
resource.
The client might send:
DELETE /yang-api/transaction/12345
Host: example.com
The server might reply as follows.
HTTP/1.1 204 No Content
Date: Mon, 24 Apr 2012 12:01:00 GMT
Server: example-server
5.5.4. Transaction Operations
There are a small number of operation resources available for
transaction resources. These are protocol operations beyond the
basic CRUD operations allowed for the data resources within the
transaction datastore.
5.5.4.1. commit
The "commit" operation is used to apply the contents of the
transaction datastore to the running configuration datastore.
If this operation succeeds then a "204 No Content" Status-Line is
sent in the response message. If the operation fails, the
appropriate error code is set according to the rules in Section 6,
and the error report is sent in the response, according to the format
defined in Section 6.1.
Example:
The following message exchange shows a commit operation. The client
might send:
POST /yang-api/transaction/12345/commit
Host: example.com
The server might reply as follows:
HTTP/1.1 204 No Content
Date: Mon, 25 Apr 2012 01:21:00 GMT
Server: example-server
Last-Modified: Mon, 25 Apr 2012 01:21:00 GMT
ETag: ab34530de24c
5.5.4.2. discard-changes
The "discard-changes" operation is used to replace the contents of
the transaction datastore with the contents of the running
configuration datastore.
If this operation succeeds then a "204 No Content" Status-Line is
sent in the response message. If the operation fails, the
appropriate error code is set according to the rules in Section 6,
and the error report is sent in the response, according to the format
defined in Section 6.1.
Example:
The following message exchange shows a discard-changes operation.
The client might send:
POST /yang-api/transaction/12345/discard-changes
Host: example.com
The server might reply as follows.
HTTP/1.1 204 No Content
Date: Mon, 25 Apr 2012 01:22:00 GMT
Server: example-server
Last-Modified: Mon, 25 Apr 2012 01:22:00 GMT
ETag: ee3498de24c
5.5.4.3. update
The "update" operation is used to merge the contents of the running
configuration datastore into the transaction datastore. If any
editing conflicts are detected that cannot be resolved by the server,
then the update operation MUST fail, and the transaction datastore
contents MUST remain unchanged after the operation is completed.
If this operation succeeds then a "204 No Content" Status-Line is
sent in the response message. If the operation fails, the
appropriate error code is set according to the rules in Section 6,
and the error report is sent in the response, according to the format
defined in Section 6.1.
Example:
The following message exchange shows an update operation. The client
might send:
POST /yang-api/transaction/12345/update
Host: example.com
The server might reply as follows.
HTTP/1.1 204 No Content
Date: Mon, 25 Apr 2012 01:32:00 GMT
Server: example-server
Last-Modified: Mon, 25 Apr 2012 01:32:00 GMT
ETag: ab23984de125
5.5.4.4. validate
The "validate" operation is used to validate the contents of the
transaction datastore. The server will verify that the transaction
datastore can be committed to the running configuration datastore.
If any editing conflicts are detected which cannot be resolved by the
server, then the update operation MUST fail.
If this operation succeeds then a "204 No Content" Status-Line is
sent in the response message. If the operation fails, the
appropriate error code is set according to the rules in Section 6,
and the error report is sent in the response, according to the format
defined in Section 6.1.
Example:
The following message exchange shows a validate operation. The
client might send:
POST /yang-api/transaction/12345/validate
Host: example.com
The server might reply as follows.
HTTP/1.1 204 No Content
Date: Mon, 25 Apr 2012 01:42:00 GMT
Server: example-server
Last-Modified: Mon, 25 Apr 2012 01:32:00 GMT
ETag: ab23984de125
6. Error Reporting 6. Error Reporting
HTTP Status-Lines are used to report success or failure for YANG-API HTTP Status-Lines are used to report success or failure for YANG-API
operations. The <rpc-error> element returned in NETCONF error operations. The <rpc-error> element returned in NETCONF error
responses contains some useful information. This error information responses contains some useful information. This error information
is adapted for use in YANG-API, and error information is returned for is adapted for use in YANG-API, and error information is returned for
"4xx" class of status codes. "4xx" class of status codes.
The following table summarizes the return status codes used The following table summarizes the return status codes used
specifically by YANG-API operations: specifically by YANG-API operations:
skipping to change at page 70, line 10 skipping to change at page 56, line 10
7. RelaxNG Grammar 7. RelaxNG Grammar
TBD TBD
8. YANG-API module 8. YANG-API module
RFC Ed.: update the date below with the date of RFC publication and RFC Ed.: update the date below with the date of RFC publication and
remove this note. remove this note.
<CODE BEGINS> file "ietf-yang-api@2012-05-27.yang" <CODE BEGINS> file "ietf-yang-api@2012-11-30.yang"
module ietf-yang-api { module ietf-yang-api {
namespace "urn:ietf:params:xml:ns:yang:ietf-yang-api"; namespace "urn:ietf:params:xml:ns:yang:ietf-yang-api";
prefix "api"; prefix "api";
organization organization
"IETF NETCONF (Network Configuration) Working Group"; "IETF NETCONF (Network Configuration) Working Group";
contact contact
"Editor: Andy Bierman "Editor: Andy Bierman
skipping to change at page 70, line 48 skipping to change at page 56, line 48
Relating to IETF Documents Relating to IETF Documents
(http://trustee.ietf.org/license-info). (http://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC XXXX; see This version of this YANG module is part of RFC XXXX; see
the RFC itself for full legal notices."; the RFC itself for full legal notices.";
// RFC Ed.: replace XXXX with actual RFC number and remove this // RFC Ed.: replace XXXX with actual RFC number and remove this
// note. // note.
// RFC Ed.: remove this note // RFC Ed.: remove this note
// Note: extracted from draft-bierman-netconf-yang-api-00.txt // Note: extracted from draft-bierman-netconf-yang-api-01.txt
// RFC Ed.: update the date below with the date of RFC publication // RFC Ed.: update the date below with the date of RFC publication
// and remove this note. // and remove this note.
revision 2012-05-27 { revision 2012-11-30 {
description description
"Initial revision."; "Initial revision.";
reference reference
"RFC XXXX: YANG-API Protocol."; "RFC XXXX: YANG-API Protocol.";
} }
/* /*
* Extensions * Extensions
*/ */
skipping to change at page 71, line 25 skipping to change at page 57, line 25
description description
"This extension is used to allow the client to create "This extension is used to allow the client to create
a new instance of a resource without providing a a new instance of a resource without providing a
value for the key leaf containing this statement. value for the key leaf containing this statement.
This extension is ignored for NETCONF, and only This extension is ignored for NETCONF, and only
applies to YANG-API resources and fields. applies to YANG-API resources and fields.
This extension is ignored unless it appears This extension is ignored unless it appears
directly within a 'leaf' data definition statement."; directly within a 'leaf' data definition statement.";
} }
/* }
* Operations
*/
rpc lock-datastore { <CODE ENDS>
description
"Lock the running configuration datastore for writing.";
}
rpc save-datastore { 9. IANA Considerations
description
"Save the running configuration datastore to non-volatile
storage.";
}
rpc unlock-datastore { This document registers one URI in the IETF XML registry [RFC3688].
description Following the format in RFC 3688, the following registration is
"Unlock the running configuration datastore."; requested to be made.
}
rpc commit { URI: urn:ietf:params:xml:ns:yang:ietf-yang-api
description Registrant Contact: The NETMOD WG of the IETF.
"Commit the transaction datastore contents to XML: N/A, the requested URI is an XML namespace.
the running configuration datastore.";
}
rpc discard-changes {
description
"Replace the transaction datastore contents with
the running configuration datastore contents.";
}
rpc update { This document registers one YANG module in the YANG Module Names
description registry [RFC6020].
"Attempt to merge the running configuration datastore
contents into the transaction datastore contents.";
}
rpc validate { name: ietf-yang-api
description namespace: urn:ietf:params:xml:ns:yang:ietf-yang-api
"Validate the transaction datastore contents."; prefix: api
} reference: RFC XXXX
} 10. Security Considerations
<CODE ENDS> TBD
9. IANA Considerations 11. Change Log
TBD -- RFC Ed.: remove this section before publication.
10. Security Considerations 11.1. 00-01
TBD o expanded introduction
11. Open Issues o removed transactions
o removed capabilities
o simplified editing model
o removed global protocol operations from ietf-yang-api.yang
o changed RPC operation terminology to protocol operation
o updated JSON draft reference
o updated open issues section
o updated IANA section
12. Open Issues
o Which WG should do this work? NETCONF? NETMOD? It is not clear
since YANG-API builds on concepts and standards from documents
owned by both working groups.
o Resource creation order and other dependencies between resources o Resource creation order and other dependencies between resources
are not well identified in YANG. YANG has leafrefs and instance- are not well identified in YANG. YANG has leafrefs and instance-
identifiers, which can be used to identify some order identifiers, which can be used to identify some order
dependencies. Are any new mechanisms needed in YANG-API needed to dependencies. Are any new mechanisms needed in YANG-API needed to
identify resource creation order and other dependency identify resource creation order and other dependency
requirements? requirements?
o There is no "message-id" field in a YANG-API message. Is a o There is no "message-id" field in a YANG-API message. Is a
message identifier needed? If so, should either the "Message-ID" message identifier needed? If so, should either the "Message-ID"
or "Content-ID" header from RFC 2392 be used for this purpose? or "Content-ID" header from RFC 2392 be used for this purpose?
o The non-configuration data resources are combined with the
configuration data resources within the YANG-API datastore. The
"config" query parameter is used to pick 1 or the other for GET
operations. Is this the best way to deal with YANG config-stmt?
Should YANG-API follow the same data classifications as YANG (i.e.
config=true|false), or create something new? Note that
transactions are config=true only, like the candidate datastore in
NETCONF.
o Should confirmed commit be added? If so, how? Should NETCONF
"confirmed-commit" procedure be used exactly for the transaction
commit operation, or should a new procedure be defined?
o Should datastore operations be added for "backup" and "restore"
functionality?
o Should sessions be used or not? Should "reusable sessions" be o Should sessions be used or not? Should "reusable sessions" be
used? Better for auditing? How does locking of the /yang-api/ used? Better for auditing? How does locking of the /yang-api/
datastore resource work for multiple edits if a session is 1 datastore resource work for multiple edits if a session is 1
operation? When does the server release the lock and decide it operation? When does the server release the lock and decide it
has been abandoned or client was disconnected? has been abandoned or client was disconnected?
o What syntax should be used for the "select" query parameter? o What syntax should be used for the "select" query parameter?
o Should the "/yang-api/modules" field within the API resource be a o Should the "/yang-api/modules" field within the API resource be a
separate resource, with its own timestamp? Currently the API separate resource, with its own timestamp? Currently the API
timestamp is coupled to any changes to the list of loaded modules. timestamp is coupled to any changes to the list of loaded modules.
Should the API resource be static and cacheable? Should the API resource be static and cacheable?
o How should resource discovery be done?
o What to do about no REMOVE operation, just DELETE? The effect is o What to do about no REMOVE operation, just DELETE? The effect is
local to the request; in a NETCONF edit-config it is worse, since local to the request; in a NETCONF edit-config it is worse, since
the netconf request might create/delete/modify many nodes the netconf request might create/delete/modify many nodes
o Should every YANG data node be a data resource and every YANG RPC o Should every YANG data node be a data resource and every YANG RPC
statement an operation resource? Is a YANG extension needed to statement an operation resource? Is a YANG extension needed to
allow data modeler control of resource boundaries? allow data modeler control of resource boundaries?
o Encoding of leafrefs? Is there some additional meta-data needed? o Encoding of leafrefs? Is there some additional meta-data needed?
Do leafref nodes need to be identified in responses (RFC 5988) or Do leafref nodes need to be identified in responses (RFC 5988) or
skipping to change at page 76, line 22 skipping to change at page 62, line 8
data? data?
o What should the default algorithm be for defining data resources? o What should the default algorithm be for defining data resources?
Should the default for an augment from another namespace be to Should the default for an augment from another namespace be to
start a new resource? Top-level data node defaults as a resource start a new resource? Top-level data node defaults as a resource
OK? OK?
o Is the token "entries" legal in the YANG-API usage of Range? What o Is the token "entries" legal in the YANG-API usage of Range? What
units should be used? "bytes" is the only token defined by HTTP. units should be used? "bytes" is the only token defined by HTTP.
o How should private transaction conflicts be handled? Currently up
to the server to decide how to handle conflicts. What happens if
there are transactions A and B. A commits. Next, B commits w/o
updating. Will A's changes be lost? Maybe. Detecting conflicts
may require a very resource-intensive implementation on the server
- may force the server to create a copy of the entire datastore
for each transaction. Want to allow a transaction to be just a
diff-set towards the datastore, so transactions are cheap.
o Does the shared transaction work like the candidate wrt to locks?
I.e. will an exclusive transaction start fail if there are
uncommitted changes?
o Need to specify the update/commit procedure in more detail so that
there is some server flexibility and client can tell what the
server will do? E.g., what causes a conflict? When is update
required before commit?
o Are all header lines used by YANG-API supported by common o Are all header lines used by YANG-API supported by common
application frameworks, such as FastCGI and WSGI? If not, then application frameworks, such as FastCGI and WSGI? If not, then
should query parameters be used instead, since the QUERY_STRING is should query parameters be used instead, since the QUERY_STRING is
widely available to WEB applications? widely available to WEB applications?
o Should the <errors> element returned in error responses be a o Should the <errors> element returned in error responses be a
separate media type? separate media type?
o Locks tied to sessions, but if don't have sessions, then how do o How should additional datastores be supported, which may be added
locks work? to the NETCONF/NETMOD framework in the future?
o Should locks be modeled as resources as operations. I.e., remove
lock-datastore and unlock-datastore operations. and transactions
will be required (exclusive mode) to write more than one operation
at a time with exclusive access.
o Should the writable-running (direct mode) be removed and just have
transaction resources, which will hide writes to running config?
o Should POST to create a new transaction for a shared candidate be
needed? Could get the same transaction ID back each ime?
Predictable resource needed instead?
o Do changes to the shared transaction show up in all copies when
the change is made?
o How can private transactions be shared securely? Are any new
access control mechanisms needed?
12. Example YANG Module 13. Example YANG Module
module example-jukebox { module example-jukebox {
namespace "http://example.com/ns/example-jukebox"; namespace "http://example.com/ns/example-jukebox";
prefix "jbox"; prefix "jbox";
import ietf-yang-api { prefix api; } import ietf-yang-api { prefix api; }
organization "Example, Inc."; organization "Example, Inc.";
description "Example Jukebox Data Model Module"; description "Example Jukebox Data Model Module";
skipping to change at page 82, line 5 skipping to change at page 67, line 5
} }
leaf song-number { leaf song-number {
type uint32; type uint32;
mandatory true; mandatory true;
description "Song number in playlist to play"; description "Song number in playlist to play";
} }
} }
} }
} }
13. Normative References 14. Normative References
[I-D.lhotka-yang-json] [I-D.lhotka-netmod-json]
Lhotka, L., "Modeling JSON Text with YANG", Lhotka, L., "Modeling JSON Text with YANG",
draft-lhotka-yang-json-00 (work in progress), April 2012. draft-lhotka-netmod-yang-json-00 (work in progress),
October 2012.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
January 2004.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, January 2005. RFC 3986, January 2005.
[RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP",
RFC 5789, March 2010. RFC 5789, March 2010.
[RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the
Network Configuration Protocol (NETCONF)", RFC 6020, Network Configuration Protocol (NETCONF)", RFC 6020,
October 2010. October 2010.
 End of changes. 103 change blocks. 
1044 lines changed or deleted 318 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/