Merge branch 'NFVSOL(25)000458_SOL026_Clause_11_API_structure_and_HTTP_methods' into 'main' (117ba7d8) · Commits · NFV - Network Functions Virtualisation / Specifications / GS NFV-SOL 026

GS_NFV-SOL_026.md

+77 −2

Original line number	Diff line number	Diff line
		@@ -1738,9 +1738,84 @@ The corresponding Redfish® API roots are specified below:
		> NOTE: The Redfish® LogService can be configured to collect logs for different kinds of Redfish® resources. The resource URI for the corresponding LogService varies accordingly. For example, the resource URI of a logging job configured for an individual ComputerSystem resource may look like /redfish/v1/Systems/{ComputerSystemId}/LogServices/{LogServiceId}. Therefore, the API root for the LogService listed above is kept generic on purpose. Full list of possible URI paths for the LogService are specified in the Redfish® data model specification [\[3\]](#_ref_3).
		.

		# 11.3 Resource structure and HTTP methods
		## 11.3 Resource structure and HTTP methods

		Figures 11.3-1 and 11.3-2 show resource structures of the Redfish® API [\[2\]](#_ref_2) resources that are applicable for the physical resource log management service interface.

		![Figure 11.3-1: API resource structure of LoggingJob and Log resources for the physical resource log management service interface](media/image32.png)

		Figure 11.3-1: API resource structure of LoggingJob and Log resources for the physical resource log management service interface

		![Figure 11.3-2: API resource structure of Subscription resource for physical resource log management service interface](media/image3.png)

		Figure 11.3-2: API resource structure of Subscription resource for physical resource log management service interface

		Table 11.3-1 lists the API resources, and the applicable HTTP methods for each resource endpoint.

		The HTTP methods marked as \"M\" (mandatory) in the \"Cat\" column of table 11.3-1 shall be supported by the PIM. The HTTP methods marked as \"O\" (optional) in the \"Cat\" column may be optionally supported by the PIM. The HTTP methods marked as \"CM\" (conditional mandatory) shall be supported by the PIM depending on the corresponding condition.

		Table 11.3-1: API Resources and HTTP methods of physical resource log management service interface<a name="table_11.3-1"></a>

		+-------------------------+---------------------------------+-----------------+----------+----------------------------------------------------------+
		\|Resource name \|Resource URI \|HTTP\ \|Cat \|Meaning \|
		\| \| \|Method \| \| \|
		+:========================+:================================+:================+:=========+:=========================================================+
		\|LoggingJobs \| /redfish/v1/.../LogServices \ \|GET \|M \|Get a collection of LoggingJobs. \|
		\| \| (see note 1) +-----------------+----------+----------------------------------------------------------+
		\| \| \|POST \|M \|Create a new \"IndividualLoggingJob\" resource. \|
		+-------------------------+---------------------------------+-----------------+----------+----------------------------------------------------------+
		\|IndividualLoggingJob \| /redfish/v1/.../LogServices \ \|GET \|M \|Get an \"IndividualLoggingJob\" resource. \|
		\| \|/{LogServiceId} (see note 1) +-----------------+----------+----------------------------------------------------------+
		\| \| \|PATCH \|M \|Modify an \"IndividualLoggingJob\" resource. \|
		\| \| +-----------------+----------+----------------------------------------------------------+
		\| \| \|PUT \|O \|Replace an \"IndividualLoggingJob\" resource. \|
		\| \| +-----------------+----------+----------------------------------------------------------+
		\| \| \|DELETE \|M \|Delete an \"IndividualLoggingJob\" resource. \|
		+-------------------------+---------------------------------+-----------------+----------+----------------------------------------------------------+
		\|Logs \| /redfish/v1/.../LogServices \ \|GET \|M \|Get a collection of Logs. \|
		\| \| /{LogServiceId}/Entries \| \| \| \|
		\| \| (see note 1) \| \| \| \|
		+-------------------------+---------------------------------+-----------------+----------+----------------------------------------------------------+
		\|IndividualLog \|/redfish/v1/.../LogServices \ \|GET \|M \|Get information about an \"IndividualLog\" resource. \|
		\| \|/{LogServiceId}/Entries \ \| \| \| \|
		\| \|/{EntryId} (see note 1) \| \| \| \|
		+-------------------------+---------------------------------+-----------------+----------+----------------------------------------------------------+
		\|Subscriptions \|/redfish/v1/EventService\ \|POST \|M \|Create a new \"Individual Subscription\" resource. \|
		\| \|/Subscriptions +-----------------+----------+----------------------------------------------------------+
		\| \| \|GET \|M \|Get the collection of all available subscriptions. \|
		+-------------------------+---------------------------------+-----------------+----------+----------------------------------------------------------+
		\|Individual Subscription \|/redfish/v1/EventService\ \|GET \|M \|Get information about the \|
		\| \|/Subscriptions/{SubscriptionId} \| \| \|\"Individual Subscription\" resource. \|
		\| \| +-----------------+----------+----------------------------------------------------------+
		\| \| \|PATCH \|M \|Modify an \"Individual Subscription\" resource. \|
		\| \| +-----------------+----------+----------------------------------------------------------+
		\| \| \|PUT \|O \|Replace an \"Individual Subscription\" resource. \|
		\| \| +-----------------+----------+----------------------------------------------------------+
		\| \| \|DELETE \|M \|Delete an \"Individual Subscription\" resource. \|
		+-------------------------+---------------------------------+-----------------+----------+----------------------------------------------------------+
		\|Notification endpoint \|{NotificationTargetURI} \|POST \|M \|Send a notification related to \|
		\| \| \| \| \|a subscribed event (see note 2). \ \|
		\| \| \| \| \|This resource can also be used to notify \ \|
		\| \| \| \| \|the consumer about availability of logs. \ \|
		\| \| \| \| \|This resource is also used to send logs asynchronously \ \|
		\| \| \| \| \|to the consumer if an event triggers a log entry. \|
		+-------------------------+---------------------------------+-----------------+----------+----------------------------------------------------------+
		\|Individual Task Monitor \|/redfish/v1/TaskService\ \|GET \|CM \|Enable API consumer to monitor the \|
		\| \|/TaskMonitors/{TaskMonitorId} \| \| \|progress of an asynchronous operation \|
		\| \|(see note 3) \| \| \|as well as receive the result of the requested \|
		\| \| \| \| \|operation once the corresponding task has been completed. \|
		\| \| \| \| \|This resource endpoint shall be supported \|
		\| \| \| \| \|if the API producer supports asynchronous operations. \|
		+-------------------------+---------------------------------+-----------------+----------+----------------------------------------------------------+
		\|NOTE 1: Possible URI paths for the LogService and LogEntry resources are specified \|
		\|in the Redfish® data model specification [\[3\]](#_ref_3). \ \|
		\|NOTE 2: Notification endpoint resource and the corresponding NotficiationTargetURI \|
		\|is used by the API producer to send notifications to the API consumer. \|
		\|This resource is not produced by the API producer. \ \|
		\|NOTE 3: The URI of the task monitor is provided in the Location header \|
		\|of the HTTP response to the API consumer when the API producer returns a \"202 Accepted\" response. \|
		+---------------------------------------------------------------------------------------------------------------------------------------------------+

		<mark>Editor's Note: This sub-clause will add Resource structure and HTTP methods for the service interface.</mark>

		## 11.4 Sequence diagrams (informative)

media/image32.png

0 → 100644

+14.7 KiB

Loading image diff...

Original line number	Diff line number	Diff line
		@@ -1738,9 +1738,84 @@ The corresponding Redfish® API roots are specified below:
		> NOTE: The Redfish® LogService can be configured to collect logs for different kinds of Redfish® resources. The resource URI for the corresponding LogService varies accordingly. For example, the resource URI of a logging job configured for an individual ComputerSystem resource may look like /redfish/v1/Systems/{ComputerSystemId}/LogServices/{LogServiceId}. Therefore, the API root for the LogService listed above is kept generic on purpose. Full list of possible URI paths for the LogService are specified in the Redfish® data model specification [\[3\]](#_ref_3).
		.

		# 11.3 Resource structure and HTTP methods
		## 11.3 Resource structure and HTTP methods

		Figures 11.3-1 and 11.3-2 show resource structures of the Redfish® API [\[2\]](#_ref_2) resources that are applicable for the physical resource log management service interface.

		![Figure 11.3-1: API resource structure of LoggingJob and Log resources for the physical resource log management service interface](media/image32.png)

		Figure 11.3-1: API resource structure of LoggingJob and Log resources for the physical resource log management service interface

		![Figure 11.3-2: API resource structure of Subscription resource for physical resource log management service interface](media/image3.png)

		Figure 11.3-2: API resource structure of Subscription resource for physical resource log management service interface

		Table 11.3-1 lists the API resources, and the applicable HTTP methods for each resource endpoint.

		The HTTP methods marked as \"M\" (mandatory) in the \"Cat\" column of table 11.3-1 shall be supported by the PIM. The HTTP methods marked as \"O\" (optional) in the \"Cat\" column may be optionally supported by the PIM. The HTTP methods marked as \"CM\" (conditional mandatory) shall be supported by the PIM depending on the corresponding condition.

		Table 11.3-1: API Resources and HTTP methods of physical resource log management service interface<a name="table_11.3-1"></a>

		+-------------------------+---------------------------------+-----------------+----------+----------------------------------------------------------+
		\|Resource name \|Resource URI \|HTTP\ \|Cat \|Meaning \|
		\| \| \|Method \| \| \|
		+:========================+:================================+:================+:=========+:=========================================================+
		\|LoggingJobs \| /redfish/v1/.../LogServices \ \|GET \|M \|Get a collection of LoggingJobs. \|
		\| \| (see note 1) +-----------------+----------+----------------------------------------------------------+
		\| \| \|POST \|M \|Create a new \"IndividualLoggingJob\" resource. \|
		+-------------------------+---------------------------------+-----------------+----------+----------------------------------------------------------+
		\|IndividualLoggingJob \| /redfish/v1/.../LogServices \ \|GET \|M \|Get an \"IndividualLoggingJob\" resource. \|
		\| \|/{LogServiceId} (see note 1) +-----------------+----------+----------------------------------------------------------+
		\| \| \|PATCH \|M \|Modify an \"IndividualLoggingJob\" resource. \|
		\| \| +-----------------+----------+----------------------------------------------------------+
		\| \| \|PUT \|O \|Replace an \"IndividualLoggingJob\" resource. \|
		\| \| +-----------------+----------+----------------------------------------------------------+
		\| \| \|DELETE \|M \|Delete an \"IndividualLoggingJob\" resource. \|
		+-------------------------+---------------------------------+-----------------+----------+----------------------------------------------------------+
		\|Logs \| /redfish/v1/.../LogServices \ \|GET \|M \|Get a collection of Logs. \|
		\| \| /{LogServiceId}/Entries \| \| \| \|
		\| \| (see note 1) \| \| \| \|
		+-------------------------+---------------------------------+-----------------+----------+----------------------------------------------------------+
		\|IndividualLog \|/redfish/v1/.../LogServices \ \|GET \|M \|Get information about an \"IndividualLog\" resource. \|
		\| \|/{LogServiceId}/Entries \ \| \| \| \|
		\| \|/{EntryId} (see note 1) \| \| \| \|
		+-------------------------+---------------------------------+-----------------+----------+----------------------------------------------------------+
		\|Subscriptions \|/redfish/v1/EventService\ \|POST \|M \|Create a new \"Individual Subscription\" resource. \|
		\| \|/Subscriptions +-----------------+----------+----------------------------------------------------------+
		\| \| \|GET \|M \|Get the collection of all available subscriptions. \|
		+-------------------------+---------------------------------+-----------------+----------+----------------------------------------------------------+
		\|Individual Subscription \|/redfish/v1/EventService\ \|GET \|M \|Get information about the \|
		\| \|/Subscriptions/{SubscriptionId} \| \| \|\"Individual Subscription\" resource. \|
		\| \| +-----------------+----------+----------------------------------------------------------+
		\| \| \|PATCH \|M \|Modify an \"Individual Subscription\" resource. \|
		\| \| +-----------------+----------+----------------------------------------------------------+
		\| \| \|PUT \|O \|Replace an \"Individual Subscription\" resource. \|
		\| \| +-----------------+----------+----------------------------------------------------------+
		\| \| \|DELETE \|M \|Delete an \"Individual Subscription\" resource. \|
		+-------------------------+---------------------------------+-----------------+----------+----------------------------------------------------------+
		\|Notification endpoint \|{NotificationTargetURI} \|POST \|M \|Send a notification related to \|
		\| \| \| \| \|a subscribed event (see note 2). \ \|
		\| \| \| \| \|This resource can also be used to notify \ \|
		\| \| \| \| \|the consumer about availability of logs. \ \|
		\| \| \| \| \|This resource is also used to send logs asynchronously \ \|
		\| \| \| \| \|to the consumer if an event triggers a log entry. \|
		+-------------------------+---------------------------------+-----------------+----------+----------------------------------------------------------+
		\|Individual Task Monitor \|/redfish/v1/TaskService\ \|GET \|CM \|Enable API consumer to monitor the \|
		\| \|/TaskMonitors/{TaskMonitorId} \| \| \|progress of an asynchronous operation \|
		\| \|(see note 3) \| \| \|as well as receive the result of the requested \|
		\| \| \| \| \|operation once the corresponding task has been completed. \|
		\| \| \| \| \|This resource endpoint shall be supported \|
		\| \| \| \| \|if the API producer supports asynchronous operations. \|
		+-------------------------+---------------------------------+-----------------+----------+----------------------------------------------------------+
		\|NOTE 1: Possible URI paths for the LogService and LogEntry resources are specified \|
		\|in the Redfish® data model specification [\[3\]](#_ref_3). \ \|
		\|NOTE 2: Notification endpoint resource and the corresponding NotficiationTargetURI \|
		\|is used by the API producer to send notifications to the API consumer. \|
		\|This resource is not produced by the API producer. \ \|
		\|NOTE 3: The URI of the task monitor is provided in the Location header \|
		\|of the HTTP response to the API consumer when the API producer returns a \"202 Accepted\" response. \|
		+---------------------------------------------------------------------------------------------------------------------------------------------------+

		<mark>Editor's Note: This sub-clause will add Resource structure and HTTP methods for the service interface.</mark>

		## 11.4 Sequence diagrams (informative)

Admin message