Automating z/OS through z/OSMF: the jobs, datasets, and files REST APIs

What it is

z/OS Management Facility (z/OSMF) is IBM's browser-based, task-oriented interface to z/OS system programming tasks, aimed at making the system approachable to staff who are not already fluent in TSO/ISPF panels. Underneath its UI, z/OSMF exposes the same functions as REST services over HTTPS: a jobs interface to submit, list, and query batch jobs and retrieve their spool output; a datasets and files interface to list, read, and write classic datasets and z/OS UNIX files; and further interfaces for other system-programming tasks. For an agent, these REST APIs are the practical alternative to driving TSO/ISPF or SDSF through terminal emulation: they return structured JSON over ordinary HTTP verbs (GET, PUT, POST, DELETE) instead of positional screen text.

Requests carry the custom header X-CSRF-ZOSMF-HEADER (its value is not significant; IBM's sample client sends zosmf), which exists to prevent cross-site request forgery; a state-changing call without it is rejected even with valid credentials, and IBM's sample sends it on reads too. A job is submitted with PUT /zosmf/restjobs/jobs and the JCL as text/plain body; status comes from GET /zosmf/restjobs/jobs/{jobname}/{jobid} (finished when status is OUTPUT, with retcode such as CC 0000, ABEND S0C7 or JCL ERROR), and spool from .../{jobid}/files and .../files/{id}/records. Datasets live under /zosmf/restfiles/ds/{dsname} (list with ?dslevel=HLQ.*) and UNIX files under /zosmf/restfiles/fs/{path}.

Why it matters

Treating z/OSMF as "just another REST API" without the CSRF header is the most common first integration failure; and because the jobs/datasets/files APIs map closely onto the underlying JES and dataset concepts (a submitted job still gets a JES job ID, a dataset write still has to satisfy RECFM/LRECL and access-authority rules), understanding the JCL/dataset basics first (see the other z/OS articles) makes the REST responses easier to interpret rather than opaque.

How to apply

• Set X-CSRF-ZOSMF-HEADER on every request; it is harmless on reads and required on writes.
• Authenticate over HTTPS with what the local z/OSMF accepts: typically HTTP basic authentication with the SAF (RACF) user ID and password, a client certificate, or the session token cookie returned by a first authenticated request. The user ID also needs z/OSMF authorization (commonly membership in the IZUUSER group).
• Use the jobs API's status polling rather than fixed sleeps to detect job completion, and fetch spool output through the same API rather than falling back to SDSF once a workflow is automated.
• Treat non-2xx HTTP responses as the primary error signal; z/OSMF returns problem details in the JSON body rather than a 3270 message code.

Pitfalls

• Reusing a session cookie or token past its configured timeout and getting authentication failures that look like authorization failures.
• Assuming the REST jobs API bypasses RACF dataset or job-class authority checks; it does not — the same access controls apply as for any other submitter.