Red Hat Summit Red Hat SummitApoyoConsolaDesarrolladoresIniciar una pruebaContacto

Este contenido no está disponible en el idioma seleccionado.

7.3. Resources

This section examines common features for resources.
22632%2C+Console+Developer+Guide-322-09-2014+17%3A11%3A35Report a bug

7.3.1. Retrieving a Resource
Copiar enlace

The API retrieves the state of a resource with a GET request on a URI obtained from a collection listing. 
GET /api/collection/resource_id HTTP/1.1
Accept: application/xml

HTTP/1.1 200 OK
Content-Type: application/xml

<resource id="resource_id" href="/api/collection/resource_id">
    ...
</resource>
Copy to Clipboard Toggle word wrap
22632%2C+Console+Developer+Guide-322-09-2014+17%3A11%3A35Report a bug

7.3.2. Updating a Resource
Copiar enlace

The API modifies resource properties with a PUT request containing an updated description from a previous GET request for the resource URI. Details on modifiable properties are found in the individual resource type documentation.
A PUT request requires a Content-Type: application/xml header. This informs the API of the XML representation in the body content as part of the request. 
PUT /api/collection/resource_id HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<resource>
    <name>New-Resource-Name</name>
</resource>

HTTP/1.1 200 OK
Content-Type: application/xml

<resource id="resource_id" href="/api/collection/resource_id">
    <name>New-Resource-Name</name>
    ...
</resource>
Copy to Clipboard Toggle word wrap
This does not include immutable resource properties that an API user has attempted to modify. If an attempt is made to modify a strictly immutable resource property, the API reports a 409 Conflict error with a fault representation in the response body.
Properties omitted from the representation are ignored and not changed.
22632%2C+Console+Developer+Guide-322-09-2014+17%3A11%3A35Report a bug

7.3.3. Deleting a Resource
Copiar enlace

The API deletes a resource with a DELETE request sent to its URI. 
DELETE /api/collection/resource_id HTTP/1.1
Accept: application/xml

HTTP/1.1 204 No Content
Copy to Clipboard Toggle word wrap
Some cases require optional body content in the DELETE request to specify additional properties. A DELETE request with optional body content requires a Content-Type: application/xml header to inform the API of the XML representation in the body content. If a DELETE request contains no body content, omit the Content-Type: application/xml header.
22632%2C+Console+Developer+Guide-322-09-2014+17%3A11%3A35Report a bug

7.3.4. Sub-Collection Relationships
Copiar enlace

A sub-collection relationship defines a hierarchical link between a resource and a sub-collection. The sub-collection exists or has some meaning in the context of a parent resource. For example, a volume contains bricks, which means the API maps the relationship between the volume resource and the bricks sub-collection.
Sub-collections are used to model the following relationships types:
  • 1:N mappings, where mapped resources are dependent on a parent resources. Without the parent resource, the dependent resource cannot exist. For example, the link between a volume and its bricks.
  • 1:N mappings, where mapped resources exist independently from parent resources but data is still associated with the relationship. For example, the link between a network and a cluster.
The API defines a relationship between a resource and a sub-collection using the link rel= attribute: 
GET /api/collection/resource_id HTTP/1.1
Accept: application/xml

HTTP/1.1 200 OK
Content-Type: application/xml

<resource id="resource_id" href="/api/collection/resource_id">
    ...
    <link rel="subcollection"
      href="/api/collection/resource_id/subcollection"/>
    ...
</resource>
Copy to Clipboard Toggle word wrap
The API user now queries the sub-collection. 
GET /api/collection/resource_id/subcollection HTTP/1.1
Accept: application/xml

HTTP/1.1 200 OK
Content-Type: application/xml

<subcollection>
    <subresource id="subresource_id"
      href="/api/collection/resource_id/subcollection/subresource_id">
        ...
    </subresource>
    ...
</subcollection>
Copy to Clipboard Toggle word wrap
22632%2C+Console+Developer+Guide-322-09-2014+17%3A11%3A35Report a bug

7.3.5. XML Element Relationships
Copiar enlace

XML element links act as an alternative to sub-collections to express relationships between resources. XML element links are simply elements with a "href" attribute that points to the linked element.
XML element links are used to model simple 1:N mappings between resources without a dependency and without data associated with the relationship. For example, the relationship between a host and a cluster.
Examples of such relationships include:
  • Backlinks from a resource in a sub-collection to a parent resource; or
  • Links between resources with an arbitrary relationship.

Example 7.6. Backlinking from a sub-collection resource to a resource using an XML element

GET /api/collection/resource_id/subcollection/subresource_id HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/xml

<subcollection>
    <subresource id="subresource_id"
      href="/api/collection/resource_id/subcollection/subresource_id">
        <resource id="resource_id" href="/api/collection/resource_id"/>
        ...
    </subresource>
</subcollection>
Copy to Clipboard Toggle word wrap
22632%2C+Console+Developer+Guide-322-09-2014+17%3A11%3A35Report a bug

7.3.6. Actions
Copiar enlace

Most resources include a list of action links to provide functions not achieved through the standard HTTP methods. 
<resource>
    ...
    <actions>
        <link rel="start" href="/api/collection/resource_id/start"/>
        <link rel="stop" href="/api/collection/resource_id/stop"/>
        ...
    </actions>
    ...
</resource>
Copy to Clipboard Toggle word wrap
The API invokes an action with a POST request to the supplied URI. The body of the POST requires an action representation encapsulating common and task-specific parameters.
Expand
Table 7.5. Common action parameters
Element Description
async If true, the server responds immediately with 202 Accepted and an action representation contains a href link to be polled for completion.
grace_period a grace period in milliseconds, which must expire before the action is initiated.
Individual actions and their parameters are documented in the individual resource type's documentation. Some parameters are mandatory for specific actions and their absence is indicated with a fault response.
An action also requires a Content-Type: application/xml header since the POST request requires an XML representation in the body content.
When the action is initiated asynchronously, the immediate 202 Accepted response provides a link to monitor the status of the task: 
POST /api/collection/resource_id/action HTTP/1.1
Content-Type: application/xml
Accept: application/xml

<action>
    <async>true</async>
</action>

HTTP/1.1 202 Accepted
Content-Type: application/xml

<action id="action_id"
  href="/api/collection/resource_id/action/action_id">
    <async>true</async>
    ...
<action>
Copy to Clipboard Toggle word wrap
A subsequent GET on the action URI provides an indication of the status of the asynchronous task.
Expand
Table 7.6. Action statuses
Status Description
pending Task has not yet started.
in_progress Task is in operation.
complete Task completed successfully.
failed Task failed. The returned action representation would contain a fault describing the failure.
Once the task has completed, the action is retained for an indeterminate period. Once this has expired, subsequent GETs are 301 Moved Permanently redirected back to the target resource. 
GET /api/collection/resource_id/action/action_id HTTP/1.1
Accept: application/xml

HTTP/1.1 200 OK
Content-Type: application/xml

<action id="action_id"
  href="/api/collection/resource_id/action/action_id">
    <status>
        <state>pending</state>
    </status>
    <link rel="parent" /api/collection/resource_id"/>
    <link rel="replay" href="/api/collection/resource_id/action"/>
<action>
Copy to Clipboard Toggle word wrap
An action representation also includes some links that are identified by the rel attribute:
Expand
Table 7.7. Action relationships
Type Description
parent A link back to the resource of this action.
replay A link back to the original action URI. POSTing to this URI causes the action to be re-initiated.
22632%2C+Console+Developer+Guide-322-09-2014+17%3A11%3A35Report a bug

7.3.7. Permissions
Copiar enlace

Each resource contains a permissions sub-collection. Each permission contains a user, an assigned role and the specified resource. For example: 
GET /api/collection/resource_id/permissions HTTP/1.1
Accept: application/xml

HTTP/1.1 200 OK
Content-Type: application/xml

<permissions>
    <permission id="permission-id"
      href="/api/collection/resource_id/permissions/permission_id">
        <role id="role_id" href="/api/roles/role_id"/>
        <user id="user_id" href="/api/users/user_id"/>
        <resource id="resource_id" href="/api/collection/resource_id"/>
    </permission>
    ...
</permissions>
Copy to Clipboard Toggle word wrap
A resource acquires a new permission when an API user sends a POST request with a permission representation and a Content-Type: application/xml header to the resource's permissions sub-collection. Each new permission requires a role and a user: 
POST /api/collection/resource_id/permissions HTTP/1.1
Content-Type: application/xml
Accept: application/xml

<permission>
    <role id="role_id"/>
    <user id="user_id"/>
</permission>

HTTP/1.1 201 Created
Content-Type: application/xml

<permission id="permission_id"
  href="/api/resources/resource_id/permissions/permission_id">
    <role id="role_id" href="/api/roles/role_id"/>
    <user id="user_id" href="/api/users/user_id"/>
    <resource id="resource_id" href="/api/collection/resource_id"/>
</permission>
Copy to Clipboard Toggle word wrap
22632%2C+Console+Developer+Guide-322-09-2014+17%3A11%3A35Report a bug

7.3.8. Handling Errors
Copiar enlace

Some errors require further explanation beyond a standard HTTP status code. For example, the API reports an unsuccessful resource state update or action with a fault representation in the response entity body. The fault contains a reason and detail strings. Clients must accommodate failed requests via extracting the fault or the expected resource representation depending on the response status code. Such cases are clearly indicated in the individual resource documentation. 
PUT /api/collection/resource_id HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<resource>
    <id>id-update-test</id>
</resource>

HTTP/1.1 409 Conflict
Content-Type: application/xml

<fault>
    <reason>Broken immutability constraint</reason>
    <detail>Attempt to set immutable field: id</detail>
</fault>
Copy to Clipboard Toggle word wrap
22632%2C+Console+Developer+Guide-322-09-2014+17%3A11%3A35Report a bug
Volver arriba
Red Hat logoGithubredditYoutubeTwitter

Aprender

Pruebe, compre y venda

Comunidades

Acerca de la documentación de Red Hat

Ayudamos a los usuarios de Red Hat a innovar y alcanzar sus objetivos con nuestros productos y servicios con contenido en el que pueden confiar. Explore nuestras recientes actualizaciones.

Hacer que el código abierto sea más inclusivo

Red Hat se compromete a reemplazar el lenguaje problemático en nuestro código, documentación y propiedades web. Para más detalles, consulte el Blog de Red Hat.

Acerca de Red Hat

Ofrecemos soluciones reforzadas que facilitan a las empresas trabajar en plataformas y entornos, desde el centro de datos central hasta el perímetro de la red.

Theme

© 2025 Red Hat