REST in plain terms
A REST API lets one program ask another for something over HTTP, the same protocol web browsers use. The request names a resource, such as an account, and an action, such as read or update; the reply carries a status code and data, usually in JSON.
A transaction by another name
You already know the shape. A CICS transaction receives an input message, runs a program, and returns an output message. A REST call is the same idea with standard packaging: the input is an HTTP request, the program behind it does the work, and the output is an HTTP response.
| HTTP method | Meaning | Rough SQL equivalent |
|---|---|---|
| GET | Read a resource | SELECT |
| POST | Create a new resource | INSERT |
| PUT | Replace a resource | UPDATE (whole row) |
| PATCH | Change part of a resource | UPDATE (some columns) |
| DELETE | Remove a resource | DELETE |
Status codes are return codes
Every response starts with a three-digit status code, which plays the same role as a return code: callers check it before looking at the data.
- 200 OK, 201 Created — it worked.
- 400 Bad Request — the caller sent invalid data, like a non-numeric amount.
- 401 / 403 — not authenticated, or not allowed.
- 404 Not Found — no such account or record.
- 500 — the server failed, the closest thing to an abend behind the API.
z/OS already speaks REST
z/OSMF provides REST services for everyday system tasks: listing datasets, reading members, submitting jobs and reading their output. Tools such as Zowe are built on them. Seeing one call makes the idea concrete.
$ curl -u USERID "https://zosmf.example.com/zosmf/restjobs/jobs?owner=USERID" HTTP/1.1 200 OK [ { "jobname": "PAYRUN01", "jobid": "JOB04512", "status": "OUTPUT", "retcode": "CC 0000" } ]
Common mistakes
GET must only read. Caches and retries assume it is safe to repeat; an update hidden behind GET can be applied several times.
If failures come back as 200 with an error message inside, callers miss them. Use the right status code, exactly as you would set a non-zero return code.
The API is a front door. The business logic still runs in the same CICS, IMS or batch programs.
What you will see at work
- Front-end and mobile developers will describe what they need in REST terms. Translating that into which transaction and which copybook is a valuable mainframe skill.
- API specifications are usually written in OpenAPI format; you will be asked to review them.
- When an API call fails, the first questions are the status code and the request — exactly like asking for the return code and the input.
Key terms
Check your understanding.
Take this lesson's quiz and save your progress. Free.