Data persistence services

The data persistence services is an application programming interface (API), which is implemented through industry standard Representational State Transfer (REST) services. A set of REST services is provided for working with user-specific data and global application data, as described in this topic.

Table 1 lists the operations that the data persistence services provide.

Table 1. Operations provided through the data persistence services
Operation	HTTP method and URI path
Persist user or application data	PUT /zosmf/IzuUICommon/persistence/user/<pluginId>/<taskId>/<resourcePath> PUT /zosmf/IzuUICommon/persistence/app/<pluginId>/<taskId>/<resourcePath>
Retrieve persisted user or application data	GET /zosmf/IzuUICommon/persistence/user/<pluginId>/<taskId>/<resourcePath> GET /zosmf/IzuUICommon/persistence/app/<pluginId>/<taskId>/<resourcePath>
Delete persisted user or application data	DELETE /zosmf/IzuUICommon/persistence/user/<pluginId>/<taskId>/<resourcePath> DELETE /zosmf/IzuUICommon/persistence/app/<pluginId>/<taskId>/<resourcePath>

Required authorizations

The user must be logged in to z/OSMF, and must have READ access to the SAF profile that was registered for the plug-in and task making the request.

For information about client authentication in z/OSMF, see Authenticating to z/OSMF.

Content type used for HTTP request and response data

The JSON content type ("Content-Type: application/json") is used for request and response data. The following JSON object is used by all data persistence services as input and output for the requested operations. The attributes provided in the JSON object depend on the requested operation.

{
 "value": "data-value",
 "version": "structure-version",
 "messages": "z/OSMF-messages",
 "update": true|false
}

where:

data-value: The value that will be added, updated, retrieved, or removed by the data persistence services. Any data type is supported including JSON objects, JSON arrays, and scalars. The value is required.
structure-version: Version of the data persistence services and the JSON object structure used for this request. The version sequence starts at 1.0.0, and is incremented only if the services or the JSON structure changes. The version the client supports is required as input to the request. The data persistence services is backward compatible for n-2 versions, and accepts requests for each version it supports. If the version specified by the client is not supported or if no version is specified, the service returns an error message.
z/OSMF-messages: z/OSMF messages received during the request. The messages attribute is included in the JSON object only if an error occurred during the request. The message ID, message text, and stack trace are provided for each z/OSMF message received.
update: An optional input attribute, which indicates that the service is updating or replacing an existing JSON object. If you set the value to true, the service updates the key-value pairs you specified for the value attribute and preserves any other data persisted in the JSON object. You can set this attribute to true only when the data type is a JSON object or JSON array. If you omit this attribute or set it to false, the service deletes the existing JSON object and creates a new JSON object that contains only the key-value pairs you specified for the value attribute.

Error handling

For errors that occur during the processing of a request, the API returns an appropriate HTTP status code to the calling client. An error is indicated by a 4nn code or a 5nn code. Some errors might also include a returned JSON object that contains a message that describes the error.

The following HTTP status codes are valid:

HTTP 200 OK: Success.
HTTP 400 Bad request: Request contained incorrect parameters.
HTTP 401 Unauthorized: Submitter of the request did not authenticate to z/OSMF or is not authorized to use the data persistence services.
HTTP 404 Bad URL: Target of the request (a URL) was not found.
HTTP 500 Internal server error: Programming error.

Error logging

Errors from the data persistence services are logged in the z/OSMF log. You can use this information to diagnose the problem or provide it to IBM® Support, if required.

For information about working with z/OSMF log files, see IBM z/OS Management Facility Configuration Guide.