Redfish data types and collections

The Redfish RESTful API introduces, among other things two important concept discussed in this section: Data types and Collections.

Data types

Each Resource resource and property of the Redfish API belong to a data type also called resource type or just type, that is mentioned in the mandatory @odata.type property returned in HTTP responses. Refer to the Redfish specification for @odata.type detail.

Each data type is associated to a set of URIs sometimes referred as instances. As an example the exhaustive list of the possible URIs of the EthernetInterface standard data type is listed in paragraph 6.31 of the DSP0268_2021.3 document. See first tabulation of the example below.

The use of the standard URI listings by Redfish clients, is explained in paragraph 2.1 of the DSP268_2021.3 document.

The first tabulation of the following example shows the exhaustive list of the EthernetInterface URIs as they appear in the DSP0268_2021.3 document. The second tabulation lists the same URIs, implemented in an HPE iLO 6 as documented in the Resource Definitions section.

/redfish/v1/Chassis/{ChassisId}/NetworkAdapters/{NetworkAdaptersId}/NetworkDeviceFunctions/{NetworkDeviceFunctionId}/EthernetInterfaces/{EthernetInterfaceId}
/redfish/v1/CompositionService/ResourceBlocks/{ResourceBlockId}/EthernetInterfaces/{EthernetInterfaceId}
/redfish/v1/CompositionService/ResourceBlocks/{ResourceBlockId}/Systems/{ComputerSystemId}/EthernetInterfaces/{EthernetInterfaceId}
/redfish/v1/Managers/{ManagerId}/EthernetInterfaces/{EthernetInterfaceId}
/redfish/v1/ResourceBlocks/{ResourceBlockId}/EthernetInterfaces/{EthernetInterfaceId}
/redfish/v1/ResourceBlocks/{ResourceBlockId}/Systems/{ComputerSystemId}/EthernetInterfaces/{EthernetInterfaceId}
/redfish/v1/Systems/{ComputerSystemId}/EthernetInterfaces/{EthernetInterfaceId}

/redfish/v1/managers/{item}/ethernetinterfaces/{item}
/redfish/v1/systems/{item}/ethernetinterfaces/{item}

The following example uses the HPE iLOrest tool to selects all the EthernetInterface data types implemented in a remote iLO 6 Redfish service and prints out the URIs (@odata.id) and associated type (@odata.type) in the second tabulation.

ilorest login <ilo-ip> -u <ilo-user> -p password
ilorest select EthernetInterface.v
ilorest select
ilorest  get "@odata.type" "@odata.id"
ilorest logout 

Current selection: EthernetInterface.v1_4_1, EthernetInterface.v1_6_3

@odata.id=/redfish/v1/Managers/1/EthernetInterfaces/1/
@odata.type=#EthernetInterface.v1_4_1.EthernetInterface

@odata.id=/redfish/v1/Managers/1/EthernetInterfaces/3/
@odata.type=#EthernetInterface.v1_4_1.EthernetInterface

@odata.id=/redfish/v1/Managers/1/EthernetInterfaces/2/
@odata.type=#EthernetInterface.v1_4_1.EthernetInterface

@odata.id=/redfish/v1/Systems/1/EthernetInterfaces/DE082000
@odata.type=#EthernetInterface.v1_6_3.EthernetInterface

@odata.id=/redfish/v1/Systems/1/EthernetInterfaces/DE07A000
@odata.type=#EthernetInterface.v1_6_3.EthernetInterface

@odata.id=/redfish/v1/Systems/1/EthernetInterfaces/DE082001
@odata.type=#EthernetInterface.v1_6_3.EthernetInterface

@odata.id=/redfish/v1/Systems/1/EthernetInterfaces/DE07A001
@odata.type=#EthernetInterface.v1_6_3.EthernetInterface

The Redfish specification allows Redfish service providers to implement their specific and added values OEM data types. The list of HPE OEM data types implemented in iLO are described in the HPE Oem extensions.

ilorest login <ilo-ip> -u <ilo-user> -p password
ilorest  types | awk '/Hpe/ && !/Collection/ {print $NF}'
ilorest logout

HpeAutomaticCertEnrollment.v1_0_0
HpeBaseConfigs.v2_0_0
HpeBiosMapping.v2_0_0
HpeBundleUpdateReport.v1_0_0
HpeCertAuth.v1_1_0
HpeCertificate.v1_0_0
HpeComponent.v1_0_1
HpeComponentInstallSet.v1_1_0
HpeComponentUpdateTask.v1_2_0
HpeDirectoryTest.v1_0_0
HpeESKM.v2_0_0
HpeHttpsCert.v2_0_0
HpeKmsConfig.v1_0_0
HpePowerMeter.v2_0_1
HpeRemoteSupport.v2_6_0
HpeSecureEraseReportService.v1_0_0
HpeSecurityService.v2_3_1
HpeServerBootSettings.v2_0_0
HpeServerConfigLock.v1_0_0
HpeServerDevice.v2_1_0
HpeServerPCISlot.v2_1_1
HpeServerPciDevice.v2_0_0
HpeTlsConfig.v1_0_0
HpeUSBPort.v2_0_0
HpeiLOAccountCertificateMap.v1_0_1
HpeiLOActiveHealthSystem.v2_5_0
HpeiLOBackupRestoreService.v2_2_0
HpeiLODateTime.v2_0_0
HpeiLOEmbeddedMedia.v2_0_0
HpeiLOFederatedGroupCapping.v2_0_0
HpeiLOFederationGroup.v2_0_0
HpeiLOFederationPeers.v2_0_0
HpeiLOGUIService.v1_1_0
HpeiLOLicense.v2_3_0
HpeiLOSSO.v2_0_0
HpeiLOSecurityDashboard.v1_0_0
HpeiLOSecurityParam.v1_1_0
HpeiLOSnmpService.v2_3_0
HpeiSCSISoftwareInitiator.v2_0_0

Resource Collections

The Redfish Data Model specification provides the following definition for resource collections. The term instances is a synonym of URIs

A resource collection is a core concept in Redfish. A resource collection is a group of like resources where the number of instances in the group can shrink or grow depending on the scope of the Redfish service or the configuration of the devices being managed. Every resource collection contains the same set of supported properties, and all contain Collection in the name of their schema. Every resource linked in the Members array within a resource collection will have the same resource type with the same major version, but can vary in minor or errata schema versions.

As per the Redfish Specification:

The value of the type property (@data.type) for resource collections shall be in the format:

#<ResourceType>.<ResourceType> where ResourceType is the resource type in the Redfish schema that defines the resource collection.

An example of a resource collection type value is #ComputerSystemCollection.ComputerSystemCollection for the ComputerSystemCollection resource collection.

Collections may be GET-only and may not accept members to be added to or removed. An examples of a GET-only collection is the Systems collection at /redfish/v1/Systems/. In a typical ComputerSystemCollection describing physical hardware, it wouldn't make sense to be able to create or remove members using POST or DELETE.

Other collections may be editable. Examples of these might be the ManagerAccountCollection at /redfish/v1/accountservice/accounts. The API supports the addition or removal of manager user accounts. To add a new member to an editable collection, perform an HTTP POST to the collection resource with a body consisting of the required JSON properties needed to create a new member (this does not necessarily require you to POST every property because many may take a unique service-assigned value or take a default value.)

The following example retrieves the ComputerSystem collection of an iLO based server. It shows the body of the response and the allowed operations on that collection. Note the Members@odata.count key containing the number of elements of the Members array.

The the elements of the Members array consists of URI links (@odata.id) to the members of the collection.

GET https://{iLO}/redfish/v1/Systems/

{
    "@odata.id": "/redfish/v1/systems/",
    "@odata.context": "/redfish/v1/$metadata/",
    "@odata.type": "#ComputerSystemCollection.ComputerSystemCollection",
    "Members@odata.count": 1,
    "Members": [
        {
            "@odata.id": "/redfish/v1/systems/1/"
        }
    ]
}

Allow: GET, HEAD

The exhaustive list of standard resource collections is present in the Redfish data Model specification.

The Redfish specification allows Redfish services to complement the data model with Oem specific extensions. HPE prefixes its OEM collection extensions with the "Hpe" string.

The following example retrieves HPE Oem extensions of an iLO 6 based server using the iLOrest tool.

ilorest login $ilo_ip -u $ilo-user -p $password
ilorest types | grep 'Hpe.*Collection'
ilorest logout

HpeBundleUpdateReportCollection
HpeCertificateCollection
HpeComponentCollection
HpeComponentInstallSetCollection
HpeComponentUpdateTaskQueueCollection
HpeInvalidImageCollection
HpeMaintenanceWindowCollection
HpeSNMPAlertDestinationCollection
HpeSNMPUsersCollection
HpeSecureEraseReportCollection
HpeServerDeviceCollection
HpeServerPCISlotCollection
HpeServerPciDeviceCollection
HpeUSBDevicesCollection
HpeUSBPortsCollection
HpeiLOAccountCertificateMapCollection
HpeiLOBackupFileCollection
HpeiLOFederationGroupCollection
HpeiLOFederationPeersCollection
HpeiLOLicenseCollection
HpeiLOSecurityParamCollection