Network Functions Virtualisation (NFV) Protocols and Data Models Specification of Patterns and Conventions For RESTful NFV-MANO APIs
Network Functions Virtualisation (NFV) Protocols and Data Models Specification of Patterns and Conventions For RESTful NFV-MANO APIs
Network Functions Virtualisation (NFV) Protocols and Data Models Specification of Patterns and Conventions For RESTful NFV-MANO APIs
1 (2020-12)
GROUP SPECIFICATION
Disclaimer
The present document has been produced and approved by the Network Functions Virtualisation (NFV) ETSI Industry
Specification Group (ISG) and represents the views of those members who participated in this ISG.
It does not necessarily represent the views of the entire ETSI membership.
2 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
Reference
RGS/NFV-SOL015ed121
Keywords
API, data, MANO, model, NFV, protocol
ETSI
Important notice
The present document may be made available in electronic versions and/or in print. The content of any electronic and/or
print versions of the present document shall not be modified without the prior written authorization of ETSI. In case of any
existing or perceived difference in contents between such versions and/or in print, the prevailing version of an ETSI
deliverable is the one made publicly available in PDF format at www.etsi.org/deliver.
Users of the present document should be aware that the document may be subject to revision or change of status.
Information on the current status of this and other ETSI documents is available at
https://portal.etsi.org/TB/ETSIDeliverableStatus.aspx
If you find errors in the present document, please send your comment to one of the following services:
https://portal.etsi.org/People/CommiteeSupportStaff.aspx
Copyright Notification
No part may be reproduced or utilized in any form or by any means, electronic or mechanical, including photocopying
and microfilm except as authorized by written permission of ETSI.
The content of the PDF version shall not be modified without the written authorization of ETSI.
The copyright and the foregoing restriction extend to reproduction in all media.
© ETSI 2020.
All rights reserved.
DECT™, PLUGTESTS™, UMTS™ and the ETSI logo are trademarks of ETSI registered for the benefit of its Members.
3GPP™ and LTE™ are trademarks of ETSI registered for the benefit of its Members and
of the 3GPP Organizational Partners.
oneM2M™ logo is a trademark of ETSI registered for the benefit of its Members and
of the oneM2M Partners.
GSM® and the GSM logo are trademarks registered and owned by the GSM Association.
ETSI
3 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
Contents
Intellectual Property Rights ................................................................................................................................6
Foreword.............................................................................................................................................................6
Modal verbs terminology....................................................................................................................................6
1 Scope ........................................................................................................................................................7
2 References ................................................................................................................................................7
2.1 Normative references ......................................................................................................................................... 7
2.2 Informative references ........................................................................................................................................ 8
3 Definition of terms, symbols and abbreviations .......................................................................................8
3.1 Terms.................................................................................................................................................................. 8
3.2 Symbols .............................................................................................................................................................. 8
3.3 Abbreviations ..................................................................................................................................................... 8
4 Conventions ..............................................................................................................................................9
4.1 Case conventions ................................................................................................................................................ 9
4.2 Conventions for URI parts ............................................................................................................................... 10
4.3 Conventions for names in data structures ......................................................................................................... 11
4.4 Conventions for documenting the API data model........................................................................................... 11
4.4.1 Overview .................................................................................................................................................... 11
4.4.2 Structured data types................................................................................................................................... 12
4.4.3 Simple data types ........................................................................................................................................ 13
4.4.4 Enumerations .............................................................................................................................................. 13
4.4.5 JSON representation of the data model....................................................................................................... 14
5 Patterns ...................................................................................................................................................14
5.1 Pattern: Creating a resource (POST) ................................................................................................................ 14
5.1.1 Description.................................................................................................................................................. 14
5.1.2 Resource definition(s) and HTTP methods ................................................................................................. 15
5.1.3 Resource representation(s) .......................................................................................................................... 15
5.1.4 HTTP Headers ............................................................................................................................................ 15
5.1.5 Response codes and error handling............................................................................................................. 15
5.2 Pattern: Creating a resource (PUT) .................................................................................................................. 16
5.2.1 Description.................................................................................................................................................. 16
5.2.2 Resource definition(s) and HTTP methods ................................................................................................. 16
5.2.3 Resource representation(s) .......................................................................................................................... 17
5.2.4 HTTP Headers ............................................................................................................................................ 17
5.2.5 Response codes and error handling............................................................................................................. 17
5.3 Pattern: Reading a resource (GET)................................................................................................................... 17
5.3.1 Description.................................................................................................................................................. 17
5.3.2 Resource definition(s) and HTTP methods ................................................................................................. 18
5.3.3 Resource representation(s) .......................................................................................................................... 18
5.3.4 HTTP Headers ............................................................................................................................................ 18
5.3.5 Response codes and error handling............................................................................................................. 18
5.4 Pattern: Querying a resource with filtering/selection (GET) ............................................................................ 18
5.4.1 Description.................................................................................................................................................. 18
5.4.2 Resource definition(s) and HTTP methods ................................................................................................. 19
5.4.3 Resource representation(s) .......................................................................................................................... 19
5.4.4 HTTP Headers ............................................................................................................................................ 19
5.4.5 Response codes and error handling............................................................................................................. 19
5.5 Pattern: Updating a resource (PATCH) ............................................................................................................ 19
5.5.1 Description.................................................................................................................................................. 19
5.5.2 Resource definition(s) and HTTP methods ................................................................................................. 20
5.5.3 Resource representation(s) .......................................................................................................................... 20
5.5.4 HTTP Headers ............................................................................................................................................ 21
5.5.5 Response codes and error handling............................................................................................................. 21
5.6 Pattern: Updating a resource (PUT) ................................................................................................................. 21
5.6.1 Description.................................................................................................................................................. 21
ETSI
4 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
ETSI
5 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
ETSI
6 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
IPRs essential or potentially essential to normative deliverables may have been declared to ETSI. The information
pertaining to these essential IPRs, if any, is publicly available for ETSI members and non-members, and can be found
in ETSI SR 000 314: "Intellectual Property Rights (IPRs); Essential, or potentially Essential, IPRs notified to ETSI in
respect of ETSI standards", which is available from the ETSI Secretariat. Latest updates are available on the ETSI Web
server (https://ipr.etsi.org/).
Pursuant to the ETSI IPR Policy, no investigation, including IPR searches, has been carried out by ETSI. No guarantee
can be given as to the existence of other IPRs not referenced in ETSI SR 000 314 (or the updates on the ETSI Web
server) which are, or may be, or may become, essential to the present document.
Trademarks
The present document may include trademarks and/or tradenames which are asserted and/or registered by their owners.
ETSI claims no ownership of these except for any which are indicated as being the property of ETSI, and conveys no
right to use or reproduce any trademark and/or tradename. Mention of those trademarks in the present document does
not constitute an endorsement by ETSI of products, services or organizations associated with those trademarks.
Foreword
This Group Specification (GS) has been produced by ETSI Industry Specification Group (ISG) Network Functions
Virtualisation (NFV).
"must" and "must not" are NOT allowed in ETSI deliverables except when used in direct citation.
ETSI
7 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
1 Scope
The present document defines patterns and conventions for RESTful NFV-MANO API specifications, gives
recommendations on API versioning and provides an API specification template.
The present document defines provisions to be followed by the ETSI NFV Industry Specification Group (ISG) when
creating RESTful NFV-MANO API specifications. The provisions do not apply to implementations.
2 References
Referenced documents which are not found to be publicly available in the expected location might be found at
https://docbox.etsi.org/Reference.
NOTE: While any hyperlinks included in this clause were valid at the time of publication, ETSI cannot guarantee
their long term validity.
The following referenced documents are necessary for the application of the present document.
[1] ETSI GS NFV-SOL 013: "Network Functions Virtualisation (NFV) Release 2; Protocols and Data
Models; Specification of common aspects for RESTful NFV MANO APIs".
[4] IETF RFC 7232: "Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests".
[5] IETF RFC 3986: "Uniform Resource Identifier (URI): Generic Syntax".
[6] IETF RFC 7233: "Hypertext Transfer Protocol (HTTP/1.1): Range Requests".
[7] IETF RFC 7231: "Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content".
ETSI
8 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
NOTE: While any hyperlinks included in this clause were valid at the time of publication, ETSI cannot guarantee
their long term validity.
The following referenced documents are not necessary for the application of the present document but they assist the
user with regard to a particular subject area.
[i.1] ETSI GS NFV 003: "Network Functions Virtualisation (NFV); Terminology for Main Concepts in
NFV".
3.1 Terms
For the purposes of the present document, the terms given in ETSI GS NFV 003 [i.1] apply.
3.2 Symbols
Void.
3.3 Abbreviations
For the purposes of the present document, the following abbreviations apply:
ETSI
9 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
4 Conventions
1) ALLUPPER
All letters of a string shall be uppercase letters. Digits may be used except at the first position. Other characters shall not
be used.
EXAMPLES 1 and 2:
a) MANAGEMENTINTERFACE
b) ETSINFVMANAGEMENT2
2) alllower
All letters of a string shall be lowercase letters. Digits may be used except at the first position. Other characters shall not
be used.
EXAMPLES 3 and 4:
a) managementinterface
b) etsinfvmanagement2
3) UPPER_WITH_UNDERSCORE
All letters of a string shall be uppercase letters. Digits may be used except at the first position. Word boundaries shall be
represented by the underscore "_" character. Other characters shall not be used.
EXAMPLES 5 and 6:
a) MANAGEMENT_INTERFACE
b) ETSI_NFV_MANAGEMENT_2
4) lower_with_underscore
All letters of a string shall be lowercase letters. Digits may be used except at the first position. Word boundaries shall be
represented by the underscore "_" character. Other characters shall not be used.
EXAMPLES 7 and 8:
a) management_interface
b) etsi_nfv_management_2
ETSI
10 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
5) UpperCamel
The string shall be formed by concatenating words as follows: Each word shall start with an uppercase letter (this
implies that the string starts with an uppercase letter). All other letters shall be lowercase letters. Digits may be used
except at the first position. Other characters shall not be used. Words that are abbreviations shall follow the same
scheme (i.e. first letter uppercase, all other letters lowercase).
a) ManagementInterface
b) EtsiNfvManagement2
6) lowerCamel
The string shall follow the provisions defined for UpperCamel with the following difference: The first letter shall be
lowercase (i.e. the first word starts with a lowercase letter).
a) managementInterface
b) etsiNfvManagement2
a) The path segments of a resource URI which represent a constant string shall use the "lower_with_underscore"
convention.
EXAMPLE 1: vnf_instances
b) If a resource represents a collection of entities, the last path segment of that resource's URI shall be a word in
plural.
EXAMPLE 2: …/prefix/API/1_0/users
c) For resources that are not task resources, the last path segment of the resource URI should be a (composite)
noun.
EXAMPLE 3: …/prefix/API/1_0/users
d) For resources that are task resources, the last path segment of the resource URI should be a verb, or start with a
verb.
EXAMPLES 4 and 5:
…/vnf_instances/{vnfInstanceId}/scale
…/vnf_instances/{vnfInstanceId}/scale_to_level
e) A variable name which represents a single path segment or a sequence of one or more path segments of a
resource URI shall use the "lowerCamel" convention and shall be surrounded by curly brackets. A variable in
the path part of a resource URI represents a single path segment unless it is explicitly specified that it
represents zero, one or more path segments.
EXAMPLE 6: {vnfInstanceId}
ETSI
11 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
f) Once a variable is replaced at runtime by an actual string, the string shall follow the rules for a single path
segment or one or more path segments defined in IETF RFC 3986 [5]. IETF RFC 3986 [5] disallows certain
characters from use in a path segment. Each actual RESTful NFV-MANO API specification shall define this
restriction to be followed when generating values for variables that represent a single path segment or one or
more path segments, or propose a suitable encoding (such as percent-encoding according to IETF
RFC 3986 [5]), to escape such characters if they can appear in input strings intended to be substituted for a
path segment variable.
2) Query naming
EXAMPLE 7: ?working_group=SOL
b) Variables that represent actual parameter values in queries shall use the "lowerCamel" convention and shall be
surrounded by curly brackets.
EXAMPLE 8: ?working_group={chooseAWorkingGroup}
c) Once a variable is replaced at runtime by an actual string, the convention defined in 1.f. shall apply to that
string.
EXAMPLE 1: vnfName
b) Names of arrays (i.e. those with cardinality 1..N or 0..N) shall be plural rather than singular.
c) Identifiers of information elements defined in the corresponding "interface and information model" design
stage specification (typically, ETSI NFV-IFA specification) using the name syntax "xyzStructureId" shall be
represented using the name "id."
NOTE: In the aforementioned specifications, the identifiers in scope of this convention are attributes with names
using the syntax "xyzStructureId" which are embedded in an information element named "XyzStructure"
for the purpose of identifying and/or externally referencing an instance of that information element.
EXAMPLE 4: NOT_INSTATIATED
e) The names of data types shall be represented using the "UpperCamel" convention.
The data model shall be defined using a tabular format as described in the following clauses. The name of the data type
shall be documented appropriately in the heading of the clause and in the caption of the table, preferably as shown in
clause X.6.2 in Annex A.
ETSI
12 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
Table 4.4.2-1: Template for a table defining a named structured data type
a) The name of a named data type (structured, simple or enum) that is defined elsewhere in the present
document where the data type is specified, or in a referenced document. In case of a referenced type from
another document, a reference to the defining document should be included in the "Description" column
unless included in a global clause.
b) An indication of the definition of an inlined nested structure. In case of inlining a structure, the "Data
type" column shall contain the string "Structure (inlined)", and all attributes of the inlined structure shall
be prefixed with one or more closing angular brackets ">", where the number of brackets represents the
level of nesting.
c) An indication of the definition of an inlined enumeration type. In case of inlining an enumeration type,
the "Data type" column shall contain the string "Enum (inlined)", and the "Description" column shall
contain the allowed values and their meanings.
3) If the maximum cardinality is greater than one, "Data type" may indicate the format of the list of values. If it is
an array, the format of that list may be indicated by using the key word "array(<type>)". If it is a map, the
format shall be indicated by using the key word "map(<type>)". In both cases, <type> indicates the data type
of the individual list entries. In case neither "map" nor "array" is given and the maximum cardinality is greater
than one, "array" shall be assumed as default. The presence or absence of the indication of "array" shall be
consistent between all data types in the scope of an API.
4) "Cardinality" defines the allowed number of occurrences, either as a single value, or as two values indicating
lower bound and upper bound, separated by "..". A value shall be either a non-negative integer number or an
uppercase letter that serves as a placeholder for a variable number (e.g. N).
5) "Description" describes the meaning and use of the attribute and may contain normative statements. In case of
an inlined enumeration type, the "Description" column shall define the allowed values and (optionally) their
meanings, as follows: "Permitted values:" on one line, followed by one paragraph of the following format for
each value: "- <VAL>: <Meaning of the value>".
Typically, named data types are used for a structure that is intended to be re-used for referencing from many data types,
or when modularizing big data types into smaller ones, e.g. for exposure using sub-resources. Inline data types are used
if the same inlined data type only appears in one or very few data types.
ETSI
13 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
Permitted values:
- BIG_FOOBAR: Signals a big foobar.
- SMALL_FOOBAR: Signals a small foobar.
fooBarColor Enum (inlined) 1 Signals the colour of the foo bar.
Permitted values:
- RED_FOOBAR: Signals a red foobar.
- GREEN_FOOBAR: Signals a green foobar.
firstChoice MyChoiceOneType 0..1 First choice. See note.
secondChoice map(MyChoiceTwoType) 0..N Second choice. See note.
nestedStruct Structure (inlined) 0..1 A structure that is inlined, rather than referenced via an
external type.
>someId String 1 An identifier. The level of nesting is indicated by ">".
>myNestedStruct array(Structure(inlined)) 0..N Another nested structure, one level deeper.
>>child String 1 Child node at nesting level 2, indicated by ">>".
NOTE: One of "firstChoice" or at least one of "secondChoice" but not both shall be present.
2) "Description" describes the meaning and use of the data type and may contain normative statements.
4.4.4 Enumerations
Enumerations specify a set of valid values.
Enumeration types shall be documented in tabular format, as in table 4.4.4-1 (one table row per enumeration value, one
table per enumeration type).
ETSI
14 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
1) "Enumeration value" provides a mnemonic identifier of the enum value, optionally with an integer to which
the value is mapped.
2) "Description" describes the meaning of the value and may contain normative statements.
When the data model is represented as JSON, all top-level attributes of the applicable resource or notification data type
shall be mapped into the root level of the JSON object. Individual APIs may deviate from this rule, for example when
re-using pre-existing data models. Such deviation shall be documented in the API specification.
The following example illustrates this convention. Assume the resource data type "Person" is defined as in table 4.4.5-1.
The JSON representation is illustrated in the example.
5 Patterns
ETSI
15 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
New resources are created on the origin server (API producer) as children of a parent resource. In order to request
resource creation, the API consumer sends a POST request to the parent resource and includes a representation of the
resource to be created. The API producer generates an identifier for the new resource that is unique for all child
resources in the scope of the parent resource, and concatenates this with the resource URI of the parent resource to form
the resource URI of the child resource. The API producer creates the new resource, and returns in a "201 Created"
response a representation of the created resource along with a "Location" HTTP header that contains the resource URI
of this resource.
1) Parent resource: A container that can hold zero or more child resources.
2) Created resource: A child resource of a container resource that is created as part of the operation. The resource
URI of the child resource is a concatenation of the resource URI of the parent resource with a string that is
chosen by the API producer, and that is unique in the scope of the parent resource URI.
NOTE: Compared to the entity body passed in the request, the entity body in the response may be different, as the
resource creation process may have modified the information that has been passed as input, or generated
additional attributes.
Resource creation can also be asynchronous in which case "202 Accepted" shall be returned instead of "201 Created".
See clauses 5.11 and 5.12 for more details about asynchronous operations.
ETSI
16 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
NOTE: The parent resource in this mode is implicit, i.e. it can be derived from the resource URI of the resource to
be created by omitting the last path segment but is not provided explicitly in the request.
This pattern shall be used for resource creation if the resource identifiers under the parent resource are managed by the
API consumer (see clause 5.1 for an alternative where the resource URI space is managed by the API producer).
Typically, that alternative is safer as the API producer can prevent collisions. However, there are also valid use cases
for creation by PUT, for instance when an API consumer manages different versions of a resource which are kept inside
a "store" container, and the set of "store" containers is managed by the API producer i.e. "store" containers are created
by POST.
In order to request resource creation, the API consumer sends a PUT request specifying the resource URI of the
resource to be created and includes a representation of the resource to be created. The origin server (API producer)
creates the new resource and returns in a "201 Created" response a representation of the created resource along with a
"Location" HTTP header field that contains the resource URI of this resource.
1) Created resource: A resource that is created as part of the operation. The resource URI of that resource is
passed by the API consumer in the PUT request.
ETSI
17 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
NOTE: Compared to the entity body passed in the request (ResourceRepresentation in figure 5.2.1-1), the entity
body in the response (ResourceRepresentation^ in figure 5.2.1-1) may be different, as the resource
creation process may have modified the information that has been passed as input.
• Upon successful resource creation, "201 Created" shall be returned. Upon failure, the appropriate error code
shall be returned.
• Resource creation can also be asynchronous in which case "202 Accepted" shall be returned instead of "201
Created". See clauses 5.11 and 5.12 for more details about asynchronous operations.
In case the resource already exists:
• If the "Update by PUT" operation is not supported for the resource, the request shall be rejected with "403
Forbidden", and a "ProblemDetails" payload should be included to provide more information about the error.
• If the "Update by PUT" operation is supported for the resource, interpret the request as an update request, i.e.
the request shall be processed as defined in clause 5.6.
See clause 5.3 for the related "query" pattern which allows to obtain a representation of a resource that has child
resources and allows to influence the content of the representation using query parameters.
ETSI
18 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
Typically, query parameters are used for controlling the content of the returned resource representation, including:
Figure 5.4.1-1 illustrates querying a resource. The query parameters are just examples based on a subset of the
parameters defined in ETSI GS NFV-SOL 013 [1].
Two typical query mechanisms are attribute-based filtering and attribute selectors.
Attribute-based filtering allows to restrict the set of objects (i.e. the set of representations of child resources) in the
returned representation to a subset that matches a set of filtering criteria applied to the values of the attributes of the
objects. The mechanism is specified in clause 5.2 of ETSI GS NFV-SOL 013 [1].
Attribute selectors allow to restrict the set of attributes of the objects (i.e. the set of attributes in the representations of
child resources) in the returned representation to a subset of the attributes as defined in the selector criteria. The
mechanism is specified in clause 5.3 of ETSI GS NFV-SOL 013 [1].
ETSI
19 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
The entity body of the response shall be an array of representations of child resources, adapted to match the query
parameters passed in the request.
NOTE: There is an alternative to use PUT to update a resource which overwrites the resource completely with the
representation passed in the payload body of the PUT request. PUT is not used for the update of
structured data in RESTful NFV-MANO APIs but is used to upload raw files.
PATCH does not carry a representation of the resource in the entity body, but a document that instructs the API
producer how to modify the resource representation. In the RESTful NFV-MANO API specifications, JSON Merge
Patch (IETF RFC 7396 [3]) is used for that purpose, which defines fragments that are merged into the target JSON
document.
ETSI
20 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
The approach illustrated above can suffer from the "lost update" phenomenon when concurrent changes are applied to
the same resource. HTTP (see IETF RFC 7232 [4]) supports conditional requests to detect such a situation and to give
the API consumer the opportunity to deal with it. For that purpose, each version of a resource gets assigned an "entity
tag" (ETag) that is modified by the API producer each time the resource is changed. This information is delivered to the
API consumer in the "ETag" (entity tag) HTTP header in HTTP responses. If the API consumer wishes that the API
producer executes the PATCH only if the ETag has not changed since the time it has last read the resource (GET), the
API consumer adds to the PATCH request the HTTP header "If-Match" with the ETag value obtained from the GET
request. The API producer executes the PATCH request only if the ETag in the "If-Match" HTTP header matches the
current ETag of the resource and responds with "412 Precondition Failed" otherwise. This is illustrated in
figure 5.5.1-2.
Figure 5.5.1-2: Resource update flow with PATCH, considering concurrent updates
Wherever applicable, it is recommended to use the JSON Merge Patch format defined by IETF RFC 7396 [3]. It needs
to be pointed out that IETF RFC 7396 [3] does not define selective update of arrays, which means that the complete
updated array always needs to be included.
However, in the RESTful NFV-MANO API specifications, many array entries are objects that contain an identifier
attribute. In order to allow providing only deltas when modifying arrays of that type, the following custom PATCH
payload format that allows to add and to update array entries is defined for use in the RESTful NFV-MANO APIs. The
payload can be used instead of or in combination with JSON Merge Patch.
ETSI
21 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
Assumptions:
1) "oldList" is the array to be modified (part of the resource representation) and "newList" is the array in the
"Modifications" document (the payload body of the PATCH request) that contains the changes.
3) A "newEntry" has a "corresponding entry" if there exists an "oldEntry" that has the same content of an
identifier attribute (typically named "id") as the "newEntry"; a "newEntry" has no corresponding entry if no
such "oldEntry" exists.
4) In any array of "oldEntry" and "newEntry" structures, the content of the identifier attribute is unique (i.e. there
are no two entries with the same content of the identifier attribute).
5) "DeleteIdList" is a parameter that can be supplied as part of the PATCH payload alongside "newList",
containing values of the identifier attribute that represent entries of "oldList" to be removed from the list as
part of the update.
Provisions:
1) For each "newEntry" in "newList" that has no corresponding entry in "oldList", the "oldList" array shall be
modified by adding that "newEntry".
2) For each "newEntry" in "newList" that has a corresponding "oldEntry" in "oldList", the value of "oldEntry"
shall be updated with the value of "newEntry" either by replacement or according to the rules of JSON Merge
PATCH (see IETF RFC 7396 [3]).
3) For each entry in "deleteIdList", delete the entry in "oldList" that has the same content of the identifier
attribute as the entry in "deleteIdList".
The entity body of the PATCH response may either be empty, may carry a representation of the updated resource, or
may represent the performed modifications.
If conflicts and data inconsistencies are foreseen when multiple API consumers update the same resource, each API
consumer should pass in the "If-Match" HTTP header of the PATCH request the value of the "ETag" HTTP header
received in the response to the GET request.
Resource update can also be asynchronous in which case "202 Accepted" shall be returned instead of "200 OK". See
clause 5.11 for more details about asynchronous operations.
When using the custom PATCH payload format defined in clause 5.5.3, it is an error that shall be rejected by "422
Unprocessable Entity" if a value of the identifier attribute in "deletedIdList" appears also in "newList".
ETSI
22 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
In the RESTful NFV-MANO APIs, PUT is typically used to upload bulk content; resources that have a structured
representation (JSON) are updated with PATCH.
NOTE: Compared to the payload body passed in the request, the payload body in the response can be different, as
the resource update process can have modified the information that has been passed as input.
Resource update can also be asynchronous in which case "202 Accepted" shall be returned instead of "200 OK". See
clause 5.11 for more details about asynchronous operations.
When a deleted resource is accessed subsequently by any HTTP method, typically the API producer responds with "404
Resource Not Found".
ETSI
23 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
The entity body of the response is typically empty. Alternatively, the response can include the final representation of the
resource prior to deletion.
• In the typical case of returning an empty response body, "204 No Content" shall be returned.
• Alternatively, if returning in the response body the final representation of the resource prior to deletion, "200
OK" shall be returned.
If a deleted resource is accessed subsequently by any HTTP method, the API producer shall respond with "404
Resource Not Found".
Resource deletion can also be asynchronous in which case "202 Accepted" shall be returned instead of "204 No
Content". See clause 5.11 for more details about asynchronous operations.
ETSI
24 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
A task resource is a child resource of a primary resource which is intended as an endpoint for the purpose of invoking a
non-CRUD operation. That non-CRUD operation executes a procedure that modifies the state of that actual resource in
a specific way or performs a computation and returns the result. Task resources are an escape means that allows to
incorporate aspects of a service-oriented architecture or RPC endpoints into a RESTful interface.
The only HTTP method that is supported for a task resource is POST, with an entity body that provides input
parameters to the process which is triggered by the request. Different responses to a POST request to a task resource are
possible, such as "202 Accepted" (for asynchronous invocation), "200 OK" (to provide a result of a computation based
on the state of the resource and additional parameters), "204 No Content" (to signal success but not return a result), or
"303 See Other" (to indicate that a different resource was modified). The actual code used depends greatly on the actual
system design.
EXAMPLE: …/call_sessions/{sessionId}/call_participants/{participantId}/transfer.
In case the operation modifies a primary resource and the response contains the "303 See Other" response code, the
"Location" HTTP header points to the primary resource.
• For long-running operations, "202 Accepted" is returned. See clause 5.11 for more details about asynchronous
operations.
ETSI
25 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
To manage subscriptions, the API producer needs to expose a container resource under which the API consumer can
request the creation/deletion of individual subscription resources. Those resources typically define criteria of the
subscription. Subscription resources can also be read using GET. Termination of a subscription is done by a DELETE
request.
To receive notifications, the API consumer exposes one or more notification endpoints (callback URIs) on which it can
receive POST and GET requests. When creating a subscription, the API consumer informs the API producer about the
notification endpoint (callback URI) to which the API producer will later deliver notifications related to that particular
subscription.
To deliver notifications, the API producer includes the actual notification payload in the entity body of a POST request
and sends that request to the notification endpoint(s) (callback URI(s)) it knows from the subscription(s). The API
consumer acknowledges the receipt of the notification with "204 No Content".
Figure 5.9.1-1 illustrates the management of subscriptions. Figure 5.9.1-2 illustrates the delivery of a notification.
ETSI
26 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
ETSI
27 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
1) Subscriptions resource: A resource that can hold zero or more subscription resources as child resources.
3) A notification endpoint (callback URI) that is exposed by the REST API consumer to receive the notifications.
The HTTP method to create a new individual subscription resource inside the subscriptions resource shall be POST.
The HTTP method to terminate a subscription by removing an individual subscription resource shall be DELETE.
The HTTP method to read the subscriptions resource and to read individual subscription resources shall be GET.
The HTTP method used by the API producer to deliver notifications shall be POST.
The HTTP method used by the API producer to test the notification endpoint shall be GET.
• It shall contain the URI of a notification endpoint (callback URI) that the API consumer exposes to receive
notifications. That URI shall be provided by the API consumer on subscription.
• It should contain criteria that allow the API producer to determine the events about which the API consumer
wishes to be notified. APIs may deviate from this recommendation for instance when there are just one or two
event types, or when it is essential that the API consumer is informed about all events.
• It shall contain a reference to the related subscription, using the "_links" attribute (see pattern for links,
clause 5.10).
On successfully reading an "individual subscription" resource or querying the "subscriptions" resource, "200 OK" shall
be returned.
On successful notification delivery or notification endpoint test, "204 No Content" shall be returned by the API
consumer.
On failure, the resource shall not be created and the appropriate error code shall be returned. For the error condition that
the test of the notification endpoint has failed, "422 Unprocessable Entity" shall be returned.
ETSI
28 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
Hyperlinks to other resources should be embedded into the representation of resources where applicable. For each
hyperlink, the target URI of the link and information about the meaning of the link shall be provided. Knowing the
meaning of the link (typically conveyed by the name of the object that defines the link, or by an attribute such as "rel")
allows the API consumer to automatically traverse the links to access resources related to the actual resource, in order to
perform operations on them.
Links shall be embedded in that JSON object as contained objects. The name of each contained object defines the
semantics of the particular link. The content of each link object shall be an object named "href" of type string, which
defines the target URI the link points to. The link to the actual resource shall be named "self" and shall be present in
every resource representation if links are used in that API.
As an example, the "_links" portion of a resource representation is shown that represents paged information.
Figure 5.10.3-1 illustrates the JSON schema and figure 5.10.3-2 illustrates the JSON object.
"properties": {
"_links": {
"required": ["self"],
"type": "object",
"description": "Link relations",
"properties": {
"self": {
"$ref": "#/definitions/Link"
},
"prev": {
"$ref": "#/definitions/Link"
},
"next": {
"$ref": "#/definitions/Link"
}
}
}
},
"definitions": {
"Link" : {
"type": "object",
"properties": {
"href": {"type": "string"}
},
"required": ["href"]
}
}
ETSI
29 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
{
"_links": {
"self": { "href": "http://api.example.com/my_api/v1/pages/127" },
"next": { "href": "http://api.example.com/my_api/v1/pages/128" },
"prev": { "href": "http://api.example.com/my_api/v1/pages/126" }
}
}
Figure 5.11.1-1 illustrates asynchronous operations with polling. After receiving an HTTP request that is to be
processed asynchronously, the API producer responds with "202 Accepted" and includes in a specific "Location" HTTP
header a data structure that points to a monitor resource which represents the progress of the processing operation. The
API consumer can then poll the monitor resource by using GET requests, each returning a data structure with
information about the operation, including the (application-specific) processing status such as "processing", "success"
and "failure". In the example, the initial status is set to "processing". Eventually, when the processing is finished, the
status is set to "success" (for successful completion of the operation) or "failure" (for completion with errors).
Typically, the representation of a monitor resource will include additional information, such as information about the
error cause if the operation was not successful.
ETSI
30 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
Figure 5.11.1-2 illustrates asynchronous operations with subscribe/notify. Before an API consumer issues any request
that might be processed asynchronously, it subscribes for monitor change notifications. Later, after receiving an HTTP
request that is to be processed asynchronously, the API producer responds with "202 Accepted" and includes in the
"Location" HTTP header a data structure that points to a monitor resource which represents the progress of the
processing operation. The API consumer can now wait for receiving a notification about the operation finishing, which
will change the status of the monitor. Once the operation is finished, the API producer will send to the API consumer a
notification with a structure in the entity body that typically includes the status of the operation (e.g. "success" or
"failure"), a link to the actual monitor affected, a link to the resource that is modified by the asynchronous operation and
application-specific further information. The API consumer can then read the monitor resource to obtain additional
information.
ETSI
31 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
1) Primary resource: The resource that is about to be created/modified/deleted by the long-running operation.
2) Monitor resource: The resource that provides information about the long-running operation.
The HTTP method applied to the primary resource can be any of POST/PUT/PATCH/DELETE.
The HTTP method applicable to read the monitor resource shall be GET.
If monitor change notifications and subscriptions to these are supported, the resources and methods described in
clause 5.9 for the RESTful subscribe/notify pattern are applicable here too.
The representation of the monitor resource shall contain at least the following information:
• Information about the operation (e.g. type, parameters, HTTP method used).
If subscribe/notify is supported, the monitor change notification shall include the status of the operation and the
resource URI of the monitor, and shall include the resource URI of the affected primary resource.
ETSI
32 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
The GET request to the monitor resource shall use "200 OK" as the response code if the monitor could be read
successfully, or the appropriate error code otherwise.
1) Parent resource: The resource under which a new child resource will be created by the long-running operation.
ETSI
33 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
The HTTP method applicable to read the created resource shall be GET.
The response to the GET request to the resource that is being created shall use the "202 Accepted" response code as
long as resource creation is ongoing.
The response to the GET request to the resource that has been successfully created shall use the "200 OK" response
code.
On failure, the appropriate error code shall be returned by the POST as well as the GET request.
Using range requests, a resource can be read in pieces, or an interrupted download can be resumed by obtaining the
missing part of the resource representation. Range requests are specified as an optional HTTP feature in IETF
RFC 7233 [6]. This clause can only provide general coverage of the pattern; [6] is the authoritative source of
information.
Figure 5.13.1-1 illustrates obtaining a partial representation of a resource. The requested range is signalled in a header
of the GET request. The response contains a header that signals the included byte range(s), and a partial resource
representation.
ETSI
34 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
The entity body of the response shall contain the part of the representation of the resource that was read, controlled by
the header information passed in the request. If a resource does not support range requests, the full representation of the
resource shall be returned instead.
The "Content-Range" response header shall be used to signal the byte range of the representation enclosed in the
payload and the complete length of the representation as defined in IETF RFC 7233 [6].
If range requests are not supported by a resource, "200 OK" shall be returned together with a full representation of the
resource.
If the information passed in the "Range" header is invalid or does not overlap with the range that can be provided as
resource representation, the "416 Range Not Satisfiable" error response shall be returned as defined by IETF
RFC 7233 [6].
Further, in table 5.14.1-2, an "id" attribute is introduced that identifies the person, i.e. its value is unique among all
instances of the data type.
ETSI
35 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
When modifying an array with PATCH (see clause 5.5), modifications can be represented by passing the whole
modified array using the JSON Merge Patch (IETF RFC 7396 [3]) format, or using an NFV-specific delta format (see
clause 5.5.3).
Figure 5.14.2-1 provides an example of a list of objects of type "PersonWithId" represented as JSON array. In this
example, the "id" attribute identifies the entries as "identifying property". If one needs to refer to this property, one
refers to "the 'id' attribute of the (entry in the) 'persons' array/list/attribute'".
In the data model notation (see Annex A), an array of elements of a particular type is denoted by the type name,
followed by a cardinality with the upper bound larger than 1 (e.g. 0..N or 1..N). Optionally, the data type may be
prefixed with the word "array" and put in parentheses.
When modifying a map with PATCH (see clause 5.5), modifications can be represented naturally by passing only the
changes using the JSON Merge Patch (IETF RFC 7396 [3]) format for the delta document. There is no need for specific
signalling.
Figure 5.14.3-1 provides an example of a list of objects of type "Person" represented as a JSON map, using the same
data as in figure 5.14.2-1. The "id" attribute is not needed here; its value is used as the name of the key. If one needs to
refer to the value of the identifying property, one refers to "the key of the 'persons' map".
ETSI
36 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
In the data model notation (see Annex A), a map of elements of a particular type is denoted by the keyword "map,
followed by the type name in parentheses, followed by a cardinality with the upper bound larger than 1 (e.g. 0..N or
1..N). Table 5.14.3-1 illustrates how to define a map.
6.1 General
The concepts and mechanisms applicable to versioning of the RESTful ETSI NFV-MANO APIs are specified in
clause 9 of ETSI GS NFV-SOL 013 [1]. ETSI ISG NFV publishes OpenAPI files [i.5] related to the APIs. This clause
defines how to document in the OpenAPI files the relationship to the corresponding GS version and the applicable API
version.
In case of the OpenAPI files provided by ETSI, the "vendor" field in the "impl" version parameter shall be set to
"etsi.org" and the "product" field in that parameter shall be set to "ETSI_NFV_OpenAPI".
EXAMPLE:
swagger: "2.0"
info:
version: "1.2.1-impl:etsi.org:ETSI_NFV_OpenAPI:1"
title: SOL003 – VNF LCM interface
license:
name: "ETSI Forge copyright notice"
url: https://forge.etsi.org/etsi-forge-copyright-notice.txt
...
A change in the 3rd field of a published GS version identifier (i.e. an editorial change) does not lead to a change in the
version identifiers of the APIs specified in the GS.
Only the version identification of published OpenAPI representations based on published GS documents is within the
scope of the present document. Non-published previews of OpenAPI representations during development shall be
clearly identifiable and distinguishable from published OpenAPI representations.
A change in the 1st or 2nd fields of the published GS version identifier (i.e. a technical change) is likely to lead to at least
a change in the minor version number of one of the APIs specified in the GS, which is documented in the definition of
the applicable API version in the GS.
ETSI
37 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
For example, if published version 2.4.1 of a base GS contains version 1.1.1 of API A, B and C, published version 3.1.1
of this base GS can contain version 1.2.1 of API A, version 2.1.1 of API B and version 1.1.1 of API C (if no changes
were made to API C).
Each OpenAPI specification shall provide in an "externalDoc" field the reference of the published base GS, including
the version identifier, as illustrated below.
EXAMPLE:
swagger: "2.0"
info:
version: "1.2.1-impl:etsi.org:ETSI_NFV_OpenAPI:1"
title: SOL003 - VNF LCM interface
description: The VNF LCM API provide access to VNF lifecycle management services
license:
name: "ETSI Forge copyright notice"
url: https://forge.etsi.org/etsi-forge-copyright-notice.txt
externalDocs:
description: ETSI GS NFV-SOL 003 version 2.3.1, 2.4.1
url : http://www.etsi.org/deliver/etsi_gs/NFV-SOL/001_099/003/02.04.01_60/gs_nfv-sol003v020401p.pdf
...
Multiple published versions of the same GS can contain the same API (e.g. SOL 003 VNF LCM API) without any
modification. In this case, all published GS versions supporting the same API should be listed in the "description"
subfield under "externalDocs", and the "url" subfield should refer to the latest version of the published base GS.
ETSI
38 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
Annex A (normative):
REST API template for interface clauses
X.1 Description
<Template note: Provides a description of the interface>
<Template note: the content formats to be supported are defined globally. If for a particular API there is
deviation from the global definition this needs to be defined here>
Figure X.3-1 shows the overall resource URI structure defined for the <long API name> API. Table X.3-1 lists the
individual resources defined, and the applicable HTTP methods.
<Template note: a node with a box represents a path segment that has at least one supported HTTP method
associated. A solid box indicates a resource strictly following the REST paradigms (subset of CRUD). A
dashed box indicates a task resource. A node without a box represents a path segment that has no
supported HTTP method associated, i.e. that merely serves for structuring the resource tree. All node names
are examples only>
ETSI
39 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
Figure X.3-1: Resource URI structure of the <long API name> interface
<Template note: A PPT template for the graph above is available in the following zip file:
gs_nfv-sol015v010201p0.zip and attached to the present document>
<Template note: In the text below, parts that are not applicable (e.g. if there are no "C" or "O" resources) can
be removed>
The <API producer> shall support responding to requests for all HTTP methods on the resources in table X.3-1 that are
marked as "M" (mandatory) in the "Cat" column and may support responding to requests for those marked as "O"
(optional). Conditions for support of responding to requests for those resources and methods marked as "C"
(conditional) in the "Cat" column by the <API producer> are defined by notes in table X.3-1.
The <API producer> shall also support the "API versions" resources as specified in clause 9.3.3 of ETSI
GS NFV-SOL 013 [<ref>].
ETSI
40 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
Table X.3-1: Resources and methods overview of the <long API name> interface
…
Notification endpoint (provided by API POST (*) <short description>. (*)
consumer) See note.
GET (*) <short description>. (*)
See note.
NOTE: The <API producer> shall support invoking the HTTP methods defined for the "Notification endpoint"
resource exposed by the <API consumer>. If the <API consumer> supports invoking the POST
method on the "Subscriptions" resource towards the <API producer>, it shall also support responding
to the HTTP requests defined for the "Notification endpoint" resource.
<Template note: In the table above, only include sub-rows for those HTTP methods that are applicable to the
resource. Only include rows defining the "Notification endpoint" and "Subscriptions" resources and the
related notes if subscribe-notify is supported in that API>
Table X.3-2: Resources and methods overview of the Foo bar interface
<Template note: This clause will be included if needed to illustrate non-trivial message flows>
ETSI
41 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
<Template note: Add flow diagram. Do not forget caption. Conventions and examples are documented in
annex B. It is recommended to use the PlantUML tool, see annex X, to create the diagram>
<placeholder for graphics, centred>
<Template note: Conventions and example for the description of a flow documented in clause 5>
<Procedure 1>, as illustrated in figure X.4.1-1, consists of the following steps:
X.5 Resources
<Template note: this clause is normative>
X.5.1 Introduction
This clause defines the resources and methods of the <long API name> API.
X.5.3.1 Description
This resource represents <something>. The API consumer can use this resource to <do something>.
ETSI
42 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
{apiRoot}/<putApiNameHere>/{apiMajorVersion}/<foo_bar>
This resource shall support the resource URI variables defined in table X.5.3.2-1.
Name Definition
apiRoot See clause 4.1 of ETSI GS NFV-SOL 013 [<ref>].
apiMajorVersion See clause X.2.
<name> <definition>
<Template note: Alternative to be used for the notification endpoint that typically has no standardized
resource URI variables>
Name Definition
none supported
X.5.3.3.1 POST
<Template note: Alternative 2>
The POST method … <Meaning(s) of the operation in API space. Add specific normative statements about what the
API producer block is expected to do when receiving this request. Also pay attention to normatively define post-
conditions, such as the fact that a new resource shall exist (after a request that creates a resource)>
This method is not supported. When this method is requested, the <API producer> shall return a "405 Method Not
Allowed" response as defined in clause 6.4 of ETSI GS NFV-SOL 013 [<ref>].
The POST method creates a foo bar object and the associated resource.
As the result of successfully executing this method, a new "FooBar" resource shall exist as defined in clause x.y.z, and
the value of the "foo" attribute in the representation of that resource shall be "bar". A notification of type
FooBarCreationNotification shall be triggered as part of successfully executing this method as defined in clause x.y.z.a.
This method shall follow the provisions specified in the tables X.5.3.3.1-1 and X.5.3.3.1-2 for URI query parameters,
request and response data structures, and response codes.
ETSI
43 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
Table X.5.3.3.1-1: URI query parameters supported by the <POST> method on this resource
Table X.5.3.3.1-3: URI query parameters supported by the POST method on this resource
ETSI
44 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
X.5.3.3.2 GET
<same structure as for POST>
X.5.3.3.3 PUT
<same structure as for POST>
X.5.3.3.4 PATCH
<same structure as for POST>
X.5.3.3.5 DELETE
<same structure as for POST>
ETSI
45 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
X.6.1 Introduction
<Template note: To be written according to the individual specification>
X.6.2.1 Introduction
This clause defines data structures to be used in resource representations and notifications.
<Template note: Provisions how to document a structured data type and an example are provided in
clause 5.4.2 of ETSI GS NFV-SOL 015>
X.6.3.1 Introduction
This clause defines data structures that can be referenced from data structures defined in the previous clauses, but can
neither be resource representations nor bound to any subscribe/notify mechanism.
X.6.4.1 Introduction
This clause defines simple data types that can be referenced from data structures defined in the previous clauses.
ETSI
46 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
ETSI
47 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
Annex B (informative):
Conventions for message flows
The appearance of the diagrams is controlled by the "skin.inc" file which is included in every PlantUML source file, as
follows:
• Save the text below in a text file named "skin.inc" and put it into the same directory as the PlantUML source
file.
skinparam monochrome true
skinparam sequenceActorBackgroundColor #FFFFFF
skinparam sequenceParticipantBackgroundColor #FFFFFF
skinparam noteBackgroundColor #FFFFFF
autonumber "#'.'"
• Use these instructions at the beginning of the PlantUML source file to include the file.
@startuml
!include skin.inc
• When making a contribution, ensure to include the PlantUML source file in a ZIP archive with the
contribution.
ETSI
48 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
6) A processing step, if there is the need to automatically number it for reference from the text, is expressed as a
"signal to self" at producer or consumer side, with a dashed slim-headed arrow.
EXAMPLE: producer -->> producer: Update internal database
7) HTTP requests and responses are numbered, usually with an increment of one. The necessary definitions for
automatic numbering are included in skin.inc (see clause B.1).
8) A message or message exchange of which the details are defined elsewhere is represented with a dashed slim-
headed arrow and set in italics.
EXAMPLE: producer -->> consumer: <i>Send XyzNotification</i>
9) A message or sequence of messages that is optional to execute, and the associated notes, are enclosed into an
"opt" section.
EXAMPLE:
opt
consumer -> producer: GET …/nice_to_have
producer -> consumer: 200 OK (NiceToHaveType)
end
11) For better structuring, long message sequences may be separated into sections using "==" separators.
EXAMPLE:
== Initialization ==
12) Further, for better structuring, multiple messages may be grouped together in a named group to show that they
belong together and serve an overarching purpose.
EXAMPLE:
group Creation and instantiation
consumer -> producer: POST …/instances (InstanceType)
producer -> consumer: 201 Created (InstanceType)
consumer -> producer: POST …/instances/{instanceId} (InstantiateRequest)
producer -> consumer: 202 Accepted ()
end
An overall example that illustrates the provisions above is given in the figures B.2-1 and B.2-2.
EXAMPLE: This example illustrates a VNF instantiation. The example might differ from the actual technical
content that has been, is or will eventually be agreed for inclusion into a GS.
@startuml
!include skin.inc
participant "NFVO" as cli
participant "VNFM" as srv
ETSI
49 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
opt
note over cli
API consumer polls the VNF lifecycle
operation occurrence resource
end note
end
opt
cli -> srv: GET …/vnf_lc_ops/abcxyz456
srv -> cli: 200 OK (LcOpOcc:status=success)
end
end
@enduml
ETSI
50 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
Figure B.2-2: Flow diagram resulting from the PlantUML source in figure B.2-1
ETSI
51 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
Annex C (normative):
Change requests classification
C.1 Introduction
This annex provides guidelines on how to fill the "Other comments" field of the Change Request (CR) template when
submitting a CR on RESTful NFV-MANO API specifications. It also provides some examples of BackWard
Compatible (BWC) and Non-BackWard Compatible (NBWC) changes to be specified in the CR template.
• Change type.
The value of "Change type" and "Change type code(s)" sub-fields shall be set according to the following rules when
submitting a CR:
1) "Change type" identifies whether the changes proposed in the CR are BackWard Compatible (BWC), Non-
BackWard Compatible (NBWC) or whether backward compatibility is Not Applicable (N/A) to these changes.
If at least one of the proposed changes in the CR is NBWC, then "Change type" shall be set to NBWC.
2) Valid values for the sub-field "Change type code(s)" are defined in the following clauses and are qualifiers of
the sub-field "Change type". When "Change type" is set to BWC then the "Change type codes" are defined in
clause C.3. In case "Change type" is set to NBWC then the "Change type codes" are defined in clause C.4.
3) When "Change type" is set to Not Applicable (N/A) then the "Change type code(s)" sub-field shall not be
filled.
CHANGE REQUEST
Version CR rev -
CR Title:
Source:
Category: Release:
ETSI
52 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
Summary of change:
Clauses affected:
Other deliverables
affected:
Figure C.2-1: Other comments field with Change Type and Change Type Code(s)
• Changing the name of a named type or changing from an inlined structure to a named data type, or from a
named data type to an inlined structure
• Error corrections
Table C.3-1 defines the list of change type codes for BWC changes on the API.
ETSI
53 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
• Removing a resource/URI
Table C.4-1 defines the list of change type codes for NBWC changes on the API.
ETSI
54 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
ETSI
55 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
Annex D (informative):
Change History
Date Version Information about changes
Initial skeleton based on
March 2019 0.1.0 - NFVSOL(19)000158r1
- NFVSOL(19)000159r1
Contributions incorporated
- NFVSOL(19)000313r3_SOL015_patterns
- NFVSOL(19)000314r2_SOL015_conventions_for_names
- NFVSOL(19)000315r2_SOL015_conventions_for_flows
June 2019 0.2.0 - NFVSOL(19)000316r3_SOL015_Annex_A_template
- NFVSOL(19)000317r1_SOL015_Annex_B_CRs_classification
Editorials
- Use "NFV-MANO" across the board
Contributions incorporated
- NFVSOL(19)000329r3_SOL015_versioning
- NFVSOL(19)000412r1_SOL015_clause_6
- NFVSOL(19)000470_SOL015_fixing_change_code
August 2019 0.3.0
Editorials
- Use "NFV-MANO" across the board
- Some placeholders in the template renamed to improve consistency
Contributions incorporated
- NFVSOL(19)000478_SOL015_Updating_PATCH_pattern
- NFVSOL(19)000479_SOL015_Updating_simple_monitor_pattern
- NFVSOL(19)000480_SOL015_add_more_PlantUML_primitives.docx
- NFVSOL(19)000536r1_SOL015_use_of_PUT
- NFVSOL(19)000537_SOL015_use_of_partial_GET
- NFVSOL(19)000544_SOL015_small_fix
October 2019 0.4.0
Editorials
- Making line styles of task resources in the resource tree consistent across GSs
- Making line style of responses consistent with our graphical conventions
- Using "(API )consumer" and "(API )producer" consistently (instead of client and
server)
- Collected abbreviations
- Fixed clause 3 to align with latest template
Contributions included
- NFVSOL(19)000538_SOL015_Fixing_Query_via_GET
- NFVSOL(19)000665_SOL015_add_none_supported
- NFVSOL(19)000683_SOL015ed271_smart_mirror_of_679_adding_error_respo
nse_for_fa
- NFVSOL(19)000666_SOL015_clarify_callbackURI__client_side_URI__notificati
November 2019 0.5.0 on_en
- NFVSOL(19)000656_SOL015_Creation_by_PUT.docx
- NFVSOL(19)000620r1_SOL015_resolve_ENs
Editorials
- Fixed the document structure after including 538.
- Removed remaining rapporteur's note.
January 2020 1.1.1 Publication by ETSI
Contributions included
May 2020 1.1.2 - NFVSOL(20)000207_SOL015ed211_adding_maps
- NFVSOL(20)000319r2_SOL015ed211_BWC_NBWC_type_code_small_fixes
Contributions included
- NFVSOL(20)000609_SOL015ed121_Remove_optionality_of_notification_endp
oint_test
- NFVSOL(20)000608r1_SOL015ed121_Conventions_for_documenting_the_dat
July 2020 1.1.3
a_model
Editorials:
- Changed name of attachment to indicate the correct version number.
ETSI
56 ETSI GS NFV-SOL 015 V1.2.1 (2020-12)
History
Document history
V1.1.1 January 2020 Publication
ETSI