Create HBA

The Create HBA operation creates an HBA and adds it to the specified partition.

HTTP method and URI

POST /api/partitions/{partition-id}/hbas

In this request, the URI variable {partition-id} is the object ID of the partition to which the HBA is to be added.

Request body contents

The request body is expected to contain a JSON object with the following fields:

Field name Type Rqd/Opt Description
name String (1-64) Required The value to be set as the HBA's name property.
description String (0-1024) Optional The value to be set as the HBA's description property.
adapter-port-uri String/ URI Required The value to be set as the HBA's adapter-port-uri property.
device-number String (4) Optional The value to be set as the HBA's device-number property.

Response body contents

On successful completion, the response body contains a JSON object with the following fields:

Field name Type Description
element-uri String/ URI The element-uri property of the newly created HBA object.

Description

The Create HBA operation creates and adds a new HBA to the partition specified by the {partition-id} portion of the request URI.

On successful execution, the element-uri field of the response body and the Location response header identify the new HBA. An Inventory Change notification is emitted asynchronously to this operation.

If this operation changes the value of any property for which property-change notifications are due, those notifications are issued asynchronously to this operation.

The URI path must designate an existing Partition object and the API user must have object-access permission to it. In addition, the adapter-port-uri field in the request body must designate an existing Storage Port of an existing adapter, and the API user must have object-access permission to that adapter.

If either of these conditions is not met, status code 404 (Not Found) is returned. In addition, the API user must have action task permission to Partition Details task; otherwise, status code 403 (Forbidden) is returned. If the request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the validation error encountered.

If the partition is in any of the transitional states ("starting" or "stopping") or CPC is not in a valid state or if the partition has the "dpm-storage-management" feature enabled, 409 (Conflict) status code is returned.

Authorization requirements

This operation has the following authorization requirements:
  • Object-access permission to the Partition object designated by {partition-id} specified in the request URI.
  • Object-access permission to the adapter containing the port designated by the adapter-port-uri field.
  • Action/task permission to the Partition Details task.

HTTP status and reason codes

On success, HTTP status code 201 (Created) is returned and the response body is provided as described in Response body contents, and the Location response header contains the URI of the newly created object.

The following HTTP status codes are returned for the indicated errors, and the response body is a standard error response body providing the reason code indicated and associated error message.

Table 1. Create HBA: HTTP status and reason codes
HTTP error status code Reason code Description
400 (Bad Request) Various Errors were detected during common request validation. See Common request validation reason codes for a list of the possible reason codes.
7 The value of device-number is not in the range as expected by the Data model - HBA element object.
8 The HBA name provided by the user is already in use by another HBA of the partition, or the provided device-number is already in use by an instance of one of the objects listed in Channel-based device numbers.
403 (Forbidden) 1 The API user does not have the required permission for this operation.
404 (Not Found) 1 The object ID in the request URI ({partition-id}) does not designated an existing Partition object, or the API user does not have object-access permission to the object.
2 The object ID in the Storage Port URI in request body field adapter-port-uri does not designate an existing Adapter object, or the API user does not have object-access permission to the object.
409 (Conflict) 1 Partition status is not valid to perform the operation.
2 Partition object with ID {partition-id} was busy and request timed out
6 The state of the CPC hosting partition is not valid to perform the operation. It must be in one of these valid states: "active", "service-required", "degraded", or "exceptions".
12 The operation is not supported when the "dpm-storage-management" feature is enabled on the partition.
116 The partition does not have sufficient resources to perform this operation.
503 (Service Unavailable) 1 The request could not be processed because the HMC is not currently communicating with an SE needed to perform the requested operation.

Additional standard status and reason codes can be returned, as described in Invoking API operations.

Example HTTP interaction

Figure 1. Create HBA: Request
POST /api/partitions/4e12c87e-c8b2-11e5-97e4-020000000192/hbas HTTP/1.1
x-api-session: p7gzv1s0wo6ops84jpy88eqspkomjrn0u887n2zm8f8l5pcnd
content-type: application/json
content-length: 134
{
   "adapter-port-uri":"/api/adapters/55a89b60-c027-11e5-80b4-020000000192/storage-ports/0",
   "device-number":"1007",
   "name":"MyHba_7"
}
Figure 2. Create HBA: Response
201 Created
server: zSeries management console API web server / 2.0
location: /api/partitions/4e12c87e-c8b2-11e5-97e4-020000000192/hbas/b6fe29c2-c8b3-11e5-
  bcda-020000000192
cache-control: no-cache
date: Mon, 01 Feb 2016 07:15:09 GMT
content-type: application/json;charset=UTF-8
content-length: 112
{
   "element-uri":"/api/partitions/4e12c87e-c8b2-11e5-97e4-020000000192/hbas/b6fe29c2-c8b3-11e5-
      bcda-020000000192"
}