Note: This bug is displayed in read-only format because the product is no longer active in Red Hat Bugzilla.

Bug 1194228

Summary:	[Docs] [Technical] Document the 'All-Content' header
Product:	Red Hat Enterprise Virtualization Manager	Reporter:	Juan Hernández <juan.hernandez>
Component:	Documentation	Assignee:	Andrew Burden <aburden>
Status:	CLOSED CURRENTRELEASE	QA Contact:	Julie <juwu>
Severity:	high	Docs Contact:
Priority:	high
Version:	3.5.0	CC:	adahms, ecohen, gklein, juan.hernandez, lbopf, lsurette, msivak, pstehlik, rbalakri, sbonazzo, s.kieske, yeylon, ylavi
Target Milestone:	ovirt-3.5.7
Target Release:	3.5.5
Hardware:	Unspecified
OS:	Unspecified
Whiteboard:	docs
Fixed In Version:		Doc Type:	Bug Fix
Doc Text:		Story Points:	---
Clone Of:	1194185	Environment:
Last Closed:	2016-01-19 11:40:47 UTC	Type:	Bug
Regression:	---	Mount Type:	---
Documentation:	---	CRM:
Verified Versions:		Category:	---
oVirt Team:	Docs	RHEL 7.3 requirements from Atomic Host:
Cloudforms Team:	---	Target Upstream Version:
Embargoed:

Description Juan Hernández 2015-02-19 11:25:04 UTC

+++ This bug was initially created as a clone of Bug #1194185 +++

Description of problem:

Some information is hidden from REST unless All-Content is set, but the header is not documented and the SDK does not support it.

One example is HA score (hosted engine) of a Host. It is set in org.ovirt.engine.api.restapi.resource.BackendHostResource#doPopulate and not present in HostMapper.

There is no way to get this data using Java SDK.

Version-Release number of selected component (if applicable):

oVirt 3.4, oVirt 3.5 components (engine, Java SDK)

How reproducible:

Always.

Additional info:

I consider HA score to be important value and I would prefer if it was always present. But that is another issue. Also the All-Content header is not properly documented anywhere and if it is then our documentation is a mess...

Comment 1 Juan Hernández 2015-02-19 11:43:43 UTC

Requests sent to the RESTAPI server can optionally contain the "All-Content" header:

  GET /ovirt-engine/api/hosts/{host:id} HTTP/1.1
  All-Content: true
  ...

When the content isn't sent the default is "false".

In general the effect of this header is to request additional data that is usually not interesting or expensive to obtain. For example, when requesting a host (or list of hosts) the caller isn't interested in the hosted engine related data, so it won't be retrieved or returned:

  GET /ovirt-engine/api/hosts/{host:id} HTTP/1.1
  ...

  HTTP/1.1 200 Ok
  <host id="...">
    <name>myhost</name>
    <!-- Note that no hosted engine information is provided. -->
    ...
  </host>

If the user is interested in that additional data it can be requested adding the header:

  GET /ovirt-engine/api/hosts/{host:id} HTTP/1.1
  All-Content: true
  ...

  HTTP/1.1 200 Ok
  <host id="...">
    <name>myhost</name>
    <hosted_engine>
      <configured>true</configured>
      <active>true</active>
      <score>3</score>
      ...
    </hosted_engine>
    ...
  </host>

The availability of the "All-Content" header is documented in the RSDL metadata that can be obtained from the live engine:

  GET /ovirt-engine/api?rsdl HTTP/1.1

  HTTP/1.1 200 Ok
  <rsdl href="/ovirt-engine/api?rsdl" rel="rsdl">
    ...
  </rsdl>

This RSDL document describes which links support the header. For example, for virtual machines:

  <link href="/ovirt-engine/api/vms" rel="get">
    <description>get all the virtual machines in the system</description>
    <request>
      <http_method>GET</http_method>
      <headers>
        <header required="false">
        <name>All-Content</name>
        <value>true|false</value>
      </header>
      ...
    </headers>
  <link>

When the header is available in a link it can be used in the Python SDK with the "all_content" parameter. For example, to get all the content of a VM:

  api.vms.get(name="myvm", all_content=True)

In the Java SDK the name of the parameter is "allContent".

What additional information is added is specific to each entity.

Comment 2 Sandro Bonazzola 2015-03-03 12:30:27 UTC

Re-targeting to 3.5.3 since this bug has not been marked as blocker for 3.5.2 and we have already released 3.5.2 Release Candidate.

Comment 4 Yaniv Lavi 2015-09-08 07:21:49 UTC

Why don't wee show all the content by default? Why do we need this option?

Comment 5 Juan Hernández 2015-09-08 08:41:59 UTC

Because computing all the content is expensive, and useless in most cases.

Comment 6 Yaniv Lavi 2015-09-08 10:04:06 UTC

(In reply to Juan Hernández from comment #5)
> Because computing all the content is expensive, and useless in most cases.

Can't we alert the user of this option within the API?

Comment 7 Juan Hernández 2015-09-08 10:05:46 UTC

How do you suggest to do that?

Comment 8 Yaniv Lavi 2015-09-08 10:08:43 UTC

(In reply to Juan Hernández from comment #7)
> How do you suggest to do that?

Add this info on the returned info that more data can be pulled with this header.

Comment 9 Juan Hernández 2015-09-08 10:10:51 UTC

I don't think that belongs into the RESTAPI, rather into the documentation. If you still think that such a thing should be part of the RESTAPI please open RFE and describe how you want it to work.

Comment 11 Julie 2015-12-23 02:29:12 UTC

Added an entry in the revision history topic and moving this bug to VERIFIED.

Comment 12 Lucy Bopf 2016-01-19 11:40:47 UTC

This content is now live on the Customer Portal in the REST API Guide. Closing.