From 728f153cc4b6e873c38fd027f07feff6d5a9e87b Mon Sep 17 00:00:00 2001 From: Giacomo Bernini Date: Wed, 17 Jul 2019 18:51:16 +0200 Subject: [PATCH] update to SOL005 NS FM --- .../NSFaultManagement/NSFaultManagement.yaml | 78 ++++++++------- .../SOL005NSFaultManagement_def.yaml | 7 +- .../NSFaultManagementNotification.yaml | 94 +++++++++++++++++-- 3 files changed, 130 insertions(+), 49 deletions(-) diff --git a/src/SOL005/NSFaultManagement/NSFaultManagement.yaml b/src/SOL005/NSFaultManagement/NSFaultManagement.yaml index 49899a4..11159ca 100644 --- a/src/SOL005/NSFaultManagement/NSFaultManagement.yaml +++ b/src/SOL005/NSFaultManagement/NSFaultManagement.yaml @@ -64,7 +64,7 @@ paths: required: false type: string description: > - Attribute-based filtering expression according to clause 4.3.2. + Attribute-based filtering expression according to clause 5.2 of ETSI GS NFV SOL 013. The NFVO shall support receiving this parameter as part of the URI query string. The OSS/BSS may supply this parameter. The following attribute names shall be supported by the NFVO in the filter @@ -82,7 +82,7 @@ paths: in: query description: > Marker to obtain the next page of a paged response. Shall be supported by the NFVO - if the NFVO supports alternative 2 (paging) according to clause 4.7.2.1 for this resource. + if the NFVO supports alternative 2 (paging) according to clause 5.4.2.1 of ETSI GS NFV SOL 013. required: false type: string - name: Accept @@ -97,11 +97,13 @@ paths: description: > 200 OK - Information about zero or more alarms was queried successfully. + Shall be returned when information about zero or more alarms has been queried successfully. The response body shall contain the list of related alarms. - If the NFVO supports alternative 2 (paging) according to - clause 4.7.2.1 for this resource, inclusion of the Link HTTP header - in this response shall follow the provisions in clause 4.7.2.3. + If the "filter" URI parameter was supplied in the request, the data in the response body shall + have been transformed according to the rules specified in clauses 5.2.2 of ETSI GS NFV-SOL 013. + If the NFVO supports alternative 2 (paging) according to clause 5.4.2.1 of ETSI GS NFV-SOL 013 + for this resource, inclusion of the Link HTTP header in this response shall follow the provisions + in clause 5.4.2.3 of ETSI GS NFV-SOL 013. headers: Content-Type: description: The MIME type of the body of the response. @@ -202,9 +204,8 @@ paths: description: > 200 OK - Information about an individual alarm was read successfully. - The response body shall contain a representation of the - individual alarm. + Shall be returned when information about an individual alarm has been read successfully. + The response body shall contain a representation of the individual alarm. headers: Content-Type: description: The MIME type of the body of the response. @@ -279,9 +280,9 @@ paths: description: > 200 OK - The request was accepted and completed. - The response body shall contain attribute modifications - for an 'Individual alarm' resource (see clause 8.5.2.4). + Shall be returned when the request has been accepted and completed. + The response body shall contain attribute modifications for an 'Individual alarm' + resource (see clause 8.5.2.4). headers: Content-Type: description: The MIME type of the body of the response. @@ -350,6 +351,8 @@ paths: The POST method creates a new subscription. This method shall follow the provisions specified in the Tables 8.4.4.3.1-1 and 8.4.4.3.1-2 for URI query parameters, request and response data structures, and response codes. + As the result of successfully executing this method, a new "Individual subscription" resource shall exist + as defined in clause 8.4.5. This method shall not trigger any notification. Creation of two subscription resources with the same callbackURI and the same filter can result in performance degradation and will provide duplicates of notifications to the OSS, and might make sense only in very rare use cases. Consequently, the NFVO may either allow creating a subscription resource if another subscription @@ -383,11 +386,9 @@ paths: description: > 201 Created - The subscription was created successfully. - The response body shall contain a representation of the - created subscription resource. - The HTTP response shall include a "Location:" HTTP - header that points to the created subscription resource. + Shall be returned when the subscription has been created successfully. + The response body shall contain a representation of the created subscription resource. + The HTTP response shall include a "Location:" HTTP header that points to the created subscription resource. schema: $ref: "definitions/SOL005NSFaultManagement_def.yaml#/definitions/FmSubscription" headers: @@ -445,16 +446,16 @@ paths: required: false type: string description: > - Attribute-based filtering expression according to clause 4.3.2. - The NFVO shall support receiving this parameter as part of the URI - query string. The OSS/BSS may supply this parameter. - All attribute names that appear in the FmSubscription and in data types - referenced from it shall be supported by the NFVO in the filter expression. + Attribute-based filtering expression according to clause 5.2 of ETSI GS NFV SOL 013. + The NFVO shall support receiving this parameter as part of the URI query string. The + OSS/BSS may supply this parameter. + All attribute names that appear in the FmSubscription and in data types referenced from it + shall be supported by the NFVO in the filter expression. - name: nextpage_opaque_marker in: query description: > - Marker to obtain the next page of a paged response. Shall be supported by the NFVO - if the NFVO supports alternative 2 (paging) according to clause 4.7.2.1 for this resource. + Marker to obtain the next page of a paged response. Shall be supported by the NFVO if the NFVO + supports alternative 2 (paging) according to clause 5.4.2.1 of ETSI GS NFV-SOL 013 for this resource. required: false type: string - name: Accept @@ -476,14 +477,15 @@ paths: description: > 200 OK - The list of subscriptions was queried successfully. - The response body shall contain in an array the representations - of all active subscriptions of the functional block that invokes - the method, i.e. zero or more representations of FM subscriptions, - as defined in clause 8.5.2.3. - If the NFVO supports alternative 2 (paging) according to - clause 4.7.2.1 for this resource, inclusion of the Link HTTP header - in this response shall follow the provisions in clause 4.7.2.3. + The list of subscriptions has been queried successfully. + The response body shall contain in an array the representations of all active subscriptions of the + functional block that invokes the method, i.e. zero or more representations of FM subscriptions, as + defined in clause 8.5.2.3. + If the "filter" URI parameter was supplied in the request, the data in the response body shall have + been transformed according to the rules specified in clause 5.2.2 of ETSI GS NFV-SOL 013. + If the NFVO supports alternative 2 (paging) according to clause 5.4.2.1 of ETSI GS NFV SOL 013 for + this resource, inclusion of the Link HTTP header in this response shall follow the provisions in + clause 5.4.2.3 of ETSI GS NFV SOL 013. headers: Content-Type: description: The MIME type of the body of the response. @@ -588,9 +590,8 @@ paths: description: > 200 OK - The operation has completed successfully. - The response body shall contain a representation of the - subscription resource. + Shall be returned when information about an individual subscription has been read successfully. + The response body shall contain a representation of the subscription resource. headers: Content-Type: description: > @@ -635,12 +636,17 @@ paths: Terminate Subscription This method terminates an individual subscription. + As the result of successfully executing this method, the "Individual subscription" resource shall + not exist any longer. This means that no notifications for that subscription shall be sent to the + formerly-subscribed API consumer. + NOTE: Due to race conditions, some notifications might still be received by the formerly-subscribed + API consumer for a certain time period after the deletion. responses: 204: description: > 204 - No Content - The subscription resource was deleted successfully. + Shall be returned when the subscription resource has been deleted successfully. The response body shall be empty. headers: WWW-Authenticate: diff --git a/src/SOL005/NSFaultManagement/definitions/SOL005NSFaultManagement_def.yaml b/src/SOL005/NSFaultManagement/definitions/SOL005NSFaultManagement_def.yaml index ab28ca2..af6df5d 100644 --- a/src/SOL005/NSFaultManagement/definitions/SOL005NSFaultManagement_def.yaml +++ b/src/SOL005/NSFaultManagement/definitions/SOL005NSFaultManagement_def.yaml @@ -304,10 +304,9 @@ definitions: format: url authentication: description: > - Authentication parameters to configure the use of Authorization when - sending notifications corresponding to this subscription. - This attribute shall only be present if the subscriber requires - authorization of notifications. + Authentication parameters to configure the use of Authorization when sending notifications + corresponding to this subscription, as defined in clause 4.5.3.4.8.3.4 of ETSI GS NFV SOL 013. + This attribute shall only be present if the subscriber requires authorization of notifications. $ref: "../../definitions/SOL005_def.yaml#/definitions/SubscriptionAuthentication" PerceivedSeverityType: diff --git a/src/SOL005/NSFaultManagementNotification/NSFaultManagementNotification.yaml b/src/SOL005/NSFaultManagementNotification/NSFaultManagementNotification.yaml index a5732c7..1a314b5 100644 --- a/src/SOL005/NSFaultManagementNotification/NSFaultManagementNotification.yaml +++ b/src/SOL005/NSFaultManagementNotification/NSFaultManagementNotification.yaml @@ -14,8 +14,8 @@ info: url: https://forge.etsi.org/etsi-forge-copyright-notice.txt externalDocs: - description: ETSI GS NFV-SOL 005 V2.5.1 - url: https://www.etsi.org/deliver/etsi_gs/NFV-SOL/001_099/005/02.05.01_60/gs_NFV-SOL005v020501p.pdf + description: ETSI GS NFV-SOL 005 V2.6.1 + url: https://www.etsi.org/deliver/etsi_gs/NFV-SOL/001_099/005/02.06.01_60/gs_NFV-SOL005v020601p.pdf basePath: /callback/v1 @@ -36,7 +36,7 @@ paths: summary: Notify about NS alarms description: > The POST method notifies an alarm related to a NS or that the alarm list has been rebuilt. - + The API consumer shall have previously created an "individual subscription resource" with a matching filter. parameters: - name: alarmNotification description: > @@ -77,7 +77,7 @@ paths: description: > 204 No Content - The notification was delivered successfully. + Shall be returned when the notification has been delivered successfully. The response body shall be empty. headers: WWW-Authenticate: @@ -106,7 +106,7 @@ paths: $ref: "../responses/SOL005_resp.yaml#/responses/503" '/URI_is_provided_by_the_client_when_creating_the_subscription-AlarmClearedNotification': - #ETSI GS NFV-SOL 005 V2.4.1 location: 8.4.6 + #ETSI GS NFV-SOL 005 V2.6.1 location: 8.4.6 post: summary: Notify about NS alarms description: > @@ -178,6 +178,70 @@ paths: $ref: "../responses/SOL005_resp.yaml#/responses/500" 503: $ref: "../responses/SOL005_resp.yaml#/responses/503" + get: + summary: Test the notification endpoint. + description: > + The GET method allows the server to test the notification endpoint that is provided by + the client, e.g. during subscription. + parameters: + - name: Accept + description: > + Content-Types that are acceptable for the response. + Reference: IETF RFC 7231 + in: header + required: true + type: string + - name: Authorization + description: > + The authorization token for the request. + Reference: IETF RFC 7235 + in: header + required: false + type: string + - name: Version + description: > + Version of the API requested to use when responding to this request. + in: header + required: true + type: string + responses: + 204: + description: > + 204 No Content + + Shall be returned when the notification endpoint has been tested successfully. + The response body shall be empty. + headers: + WWW-Authenticate: + type: string + description: > + Challenge if the corresponding HTTP request has not provided + authorization, or error details if the corresponding HTTP request + has provided an invalid authorization token. + maximum: 1 + minimum: 0 + Version: + description: > + Version of the API used in the response. + type: string + maximum: 1 + minimum: 1 + 400: + $ref: "../responses/SOL005_resp.yaml#/responses/400" + 401: + $ref: "../responses/SOL005_resp.yaml#/responses/401" + 403: + $ref: "../responses/SOL005_resp.yaml#/responses/403" + 404: + $ref: "../responses/SOL005_resp.yaml#/responses/404" + 405: + $ref: "../responses/SOL005_resp.yaml#/responses/405" + 406: + $ref: "../responses/SOL005_resp.yaml#/responses/406" + 500: + $ref: "../responses/SOL005_resp.yaml#/responses/500" + 503: + $ref: "../responses/SOL005_resp.yaml#/responses/503" '/URI_is_provided_by_the_client_when_creating_the_subscription-AlarmListRebuiltNotification': post: @@ -253,10 +317,10 @@ paths: $ref: "../responses/SOL005_resp.yaml#/responses/503" get: - summary: Test the notification endpoint + summary: Test the notification endpoint. description: > - The GET method allows the server to test the notification endpoint that is provided by the client, e.g. during - subscription. + The GET method allows the server to test the notification endpoint that is provided by + the client, e.g. during subscription. parameters: - name: Accept description: > @@ -283,7 +347,7 @@ paths: description: > 204 No Content - The notification endpoint was tested successfully. + Shall be returned when the notification endpoint has been tested successfully. The response body shall be empty. headers: WWW-Authenticate: @@ -294,12 +358,24 @@ paths: has provided an invalid authorization token. maximum: 1 minimum: 0 + Version: + description: > + Version of the API used in the response. + type: string + maximum: 1 + minimum: 1 400: $ref: "../responses/SOL005_resp.yaml#/responses/400" 401: $ref: "../responses/SOL005_resp.yaml#/responses/401" 403: $ref: "../responses/SOL005_resp.yaml#/responses/403" + 404: + $ref: "../responses/SOL005_resp.yaml#/responses/404" + 405: + $ref: "../responses/SOL005_resp.yaml#/responses/405" + 406: + $ref: "../responses/SOL005_resp.yaml#/responses/406" 500: $ref: "../responses/SOL005_resp.yaml#/responses/500" 503: -- GitLab