Creating and Exposing a Function as a REST API in OCI

Mandeep Gupta  ·  Oracle Cloud Infrastructure  ·  Integration

If you’ve ever needed a Fusion AI Agent Studio workflow to call out to custom logic that isn’t a native Fusion object — zipping a file, transforming a payload, calling a third-party service — OCI Functions plus API Gateway is the cleanest way to expose that logic as a plain REST endpoint. This walks through the full path: networking, the function itself, and the gateway that makes it callable over HTTPS.

Part 1 — Networking: VCN and Subnets

For calling out to a public HTTPS endpoint (like a Fusion/UCM SaaS URL), you don’t need anything exotic — just a subnet with a route to the internet, and the right security rules for outbound 443.

1. Use the VCN Wizard

Networking → Virtual Cloud Networks → Start VCN Wizard

Choose “Create VCN with Internet Connectivity” — this one option builds everything you need in a single shot: a VCN, one public subnet, one private subnet, an Internet Gateway, a NAT Gateway, and pre-wired route tables and security lists for each.

Fill in a name (e.g. ucm-integration-vcn) and CIDR block (the default 10.0.0.0/16 is fine unless it overlaps something you already have), then Create.

2. Check the private subnet’s route table

Console → your VCN → Subnets → private subnet → Route Table. It should already show Destination: 0.0.0.0/0  →  Target: NAT Gateway — that’s what lets your function reach the public internet outbound.

3. Check the security list allows outbound HTTPS

Same subnet page → Security Lists. The default egress rule from the wizard is usually wide open (0.0.0.0/0, all protocols).

If it’s been locked down, make sure there’s at minimum an egress rule: Destination 0.0.0.0/0, Protocol TCP, Destination Port 443.

Part 2 — Create the Functions Application

OCI Console → Developer Services → Functions → Applications

Click Create Application.

Name it (e.g. ucm-integration-app), then pick the VCN and the private subnet from Part 1.

uname -p

Part 3 — Deploy the Function from Cloud Shell

Click into your new application → Getting Started tab. OCI generates the exact commands for you, pre-filled with your compartment and app name. The overall flow:

1. Open Cloud Shell — no local install needed.
2. Upload your func.py, func.yaml, and requirements.txt into their own dedicated folder (never directly into your home directory — more on why below).
3. Run the commands the Getting Started page shows you.

Set up the Fn CLI context once per Cloud Shell setup (usually pre-configured, but confirm):

fn list contexts

mkdir -p ~/zip-file-fn
cd ~/zip-file-fn
# place func.py, func.yaml, requirements.txt HERE
pwd   # should show .../zip-file-fn, NOT your home directory

fn -v deploy --app <your-app-name>

Test it directly, bypassing any gateway:

echo '{"filename": "test.txt", "content": "hello world"}' | fn invoke <your-app-name> zip-file-fn

Expected response:

{
  "zip_filename": "test.zip",
  "zip_base64": "UEsDBBQAAAAIAA=="
}

Part 4 — Expose It via API Gateway

Only needed if something outside OCI Functions — like a Fusion AI Agent Studio External REST tool — needs to call this over HTTPS.

Create the Gateway

Developer Services → API Gateway → Gateways → Create Gateway

Type: Public.

VCN/subnet: the public subnet from Part 1.

Create a Deployment

Deployments → Create Deployment

Set a path prefix (e.g. /zip), then add a route: path /create, method POST, backend type Oracle Functions → select your application and function.

Grab the Endpoint URL from the gateway’s overview page — combined with your path prefix and route, that’s the full URL you’d register as an AI Agent Studio External REST tool target, e.g.:

POST https://<gateway-endpoint>/zip/create

Part 5 — The One Permission Everyone Forgets: Gateway → Function IAM

This is the step that trips almost everyone up. The gateway doesn’t automatically have permission to invoke your function — without this, requests fail with a generic timeout or a 500 Internal Server Error, which gives no hint that it’s actually an authorization gap.

Allow any-user to use functions-family in compartment <functions-compartment-name>
  where ALL {
    request.principal.type='ApiGateway',
    request.resource.compartment.id='<api-gateway-compartment-OCID>'
  }

Where:

• <functions-compartment-name> = the name of the compartment where your function lives
• <api-gateway-compartment-OCID> = the OCID of the compartment where your gateway lives

Create it under Identity & Security → Policies → Create Policy → Show manual editor, wait a minute or two for propagation, then retest:

curl -v https://<gateway-endpoint>/zip/create \
  -H "Content-Type: application/json" \
  -d '{"filename":"test.txt","content":"hello world"}'

Wiring It into AI Agent Studio

Once the endpoint works, register it as an External REST tool:

1. AI Agent Studio → Tools → Add, Tool Type: External REST.
2. Authorization: Instance URL is the base domain only — no path, e.g. https://<gateway-id>.apigateway.<region>.oci.customer-oci.com.
3. Functions tab: Operation Type POST, Resource Path /zip/create (the relative path only).
4. Parameters tab: each JSON body field gets its own row, Type set to Body — Oracle assembles them into the JSON payload automatically. No need to hand-craft the request body yourself.
5. Sample Queries: give the LLM a few example phrasings so it knows when to reach for this tool.

Category: Configuration | AI Agent Studio | OCI