What's Actually Inside a REST Request

Part 7 of 12 in the Oracle EPM Cloud REST API series.

The first six parts of this series covered URLs, verbs, status codes, and authentication as separate topics. This post pulls them together, because every REST call you make against Oracle EPM Cloud is built from exactly four parts, and once you can name all four without thinking, writing a new call becomes a matter of filling in a template rather than starting from scratch.

URL. The destination endpoint, built from the server, service, version, and resource pattern covered in part three. This tells Oracle EPM Cloud which resource you want to act on.

HTTP method. The verb from part four: GET, POST, PUT, or DELETE. This tells Oracle EPM Cloud what you want done with that resource.

Headers. Metadata about the request itself, separate from the resource or the action. The two you will use constantly are Content-Type: application/json, which tells the server the body is formatted as JSON, and Authorization, which carries the credentials covered in part six, either a Basic Auth value or a Bearer token.

Request body. For POST and PUT calls, the actual JSON payload describing what you want done: which job to run, with which parameters, for example. GET and DELETE calls typically skip the body entirely, since there is nothing left to describe once the URL and method are set.

Here is what those four parts look like assembled into one real request, submitting a business rule for execution:

curl -X POST \
  "https://epm-xyz.epm.us-phoenix-1.ocs.oraclecloud.com/HyperionPlanning/rest/v3/applications/Vision/jobs" \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <base64 encoded credentials>" \
  -d '{
        "jobType": "Rules",
        "jobName": "Operating Expense Adj Plan",
        "parameters": {
          "MyScenario1": "Current",
          "MyVersion1": "BU Version_1"
        }
      }'

Trace it against the four parts: the URL identifies the jobs resource for the Vision application, -X POST is the method, the two -H flags are the headers, and everything after -d is the body.

A useful habit as you start building your own calls: write out these four parts as plain notes before touching a script. Which URL. Which method. Which headers. What body, if any. Filling in that outline first, even on paper or in a comment, catches most mistakes (a missing header, a body attached to a GET where none belongs) before you run anything against a live environment.

With the shape of a request fully mapped out, the series moves from concepts into practice. Next: submitting your first real job, a business rule, and watching it run.