Outbound HTTP

DieselEngine provides OkHttp 4 as the outbound HTTP client. The okHttpClient global is available in every script for making HTTP requests to external APIs and services.

Global Bindings

Binding	Type	Description
okHttpClient	OkHttpClient	Pre-configured HTTP client instance
RequestBuilder	Class	okhttp3.Request.Builder — construct requests
RequestBody	Class	okhttp3.RequestBody — create request bodies
MediaType	Class	okhttp3.MediaType — MIME type definitions
TimeUnit	Class	java.util.concurrent.TimeUnit — for timeouts

GET Request

const response = okHttpClient.newCall(
  new RequestBuilder()
    .url("https://api.example.com/users")
    .header("Authorization", "Bearer " + apiKey)
    .build()
).execute();

const data = JSON.parse(response.body().string());
console.log(data);

POST Request (JSON)

const payload = JSON.stringify({ name: "Alice", email: "alice@example.com" });

const response = okHttpClient.newCall(
  new RequestBuilder()
    .url("https://api.example.com/users")
    .header("Content-Type", "application/json")
    .post(RequestBody.create(payload, MediaType.parse("application/json")))
    .build()
).execute();

const result = JSON.parse(response.body().string());

PUT Request

const payload = JSON.stringify({ name: "Alice Updated" });

const response = okHttpClient.newCall(
  new RequestBuilder()
    .url("https://api.example.com/users/123")
    .put(RequestBody.create(payload, MediaType.parse("application/json")))
    .build()
).execute();

DELETE Request

const response = okHttpClient.newCall(
  new RequestBuilder()
    .url("https://api.example.com/users/123")
    .delete()
    .build()
).execute();

PATCH Request

const payload = JSON.stringify({ status: "active" });

const response = okHttpClient.newCall(
  new RequestBuilder()
    .url("https://api.example.com/users/123")
    .patch(RequestBody.create(payload, MediaType.parse("application/json")))
    .build()
).execute();

Headers

const response = okHttpClient.newCall(
  new RequestBuilder()
    .url("https://api.example.com/data")
    .header("Authorization", "Bearer " + token)
    .header("Accept", "application/json")
    .header("X-Request-Id", diesel.randomUUID())
    .build()
).execute();

Response Handling

const response = okHttpClient.newCall(request).execute();

// Status code
const status = response.code();

// Response body as string
const body = response.body().string();

// Check if successful (2xx)
const ok = response.isSuccessful();

// Response headers
const contentType = response.header("Content-Type");

// Parse JSON response
if (ok) {
  const data = JSON.parse(body);
} else {
  console.error(`Request failed: ${status} - ${body}`);
}

WARNING

Always call response.body().string() to read the body. The body can only be consumed once — calling it a second time will return empty.

Form Data

const FormBody = Java.type('okhttp3.FormBody');
const formBody = new FormBody.Builder()
  .add("username", "alice")
  .add("password", "secret")
  .build();

const response = okHttpClient.newCall(
  new RequestBuilder()
    .url("https://api.example.com/login")
    .post(formBody)
    .build()
).execute();

Common Patterns

API Client Service

// /services/ExternalApiService.js
export class ExternalApiService {

  static get(path, params = {}) {
    const url = new URL("https://api.example.com" + path);
    for (const [key, value] of Object.entries(params)) {
      url.searchParams.set(key, value);
    }

    const response = okHttpClient.newCall(
      new RequestBuilder()
        .url(url.toString())
        .header("Authorization", "Bearer " + diesel.getRegistryValue("API_KEY"))
        .build()
    ).execute();

    if (!response.isSuccessful()) {
      throw new Error(`API error: ${response.code()}`);
    }

    return JSON.parse(response.body().string());
  }

  static post(path, data) {
    const response = okHttpClient.newCall(
      new RequestBuilder()
        .url("https://api.example.com" + path)
        .header("Authorization", "Bearer " + diesel.getRegistryValue("API_KEY"))
        .post(RequestBody.create(
          JSON.stringify(data),
          MediaType.parse("application/json")
        ))
        .build()
    ).execute();

    if (!response.isSuccessful()) {
      throw new Error(`API error: ${response.code()}`);
    }

    return JSON.parse(response.body().string());
  }
}

Webhook Delivery

function sendWebhook(url, event, data) {
  const payload = JSON.stringify({
    event,
    data,
    timestamp: new Date().toISOString(),
    id: diesel.randomUUID()
  });

  const response = okHttpClient.newCall(
    new RequestBuilder()
      .url(url)
      .header("Content-Type", "application/json")
      .header("X-Webhook-Signature", diesel.sha512hash(payload, webhookSecret))
      .post(RequestBody.create(payload, MediaType.parse("application/json")))
      .build()
  ).execute();

  return response.isSuccessful();
}

Proxy / Pass-Through

export function handleRequest(context) {
  // Forward the request to an upstream service
  const upstreamResponse = okHttpClient.newCall(
    new RequestBuilder()
      .url("https://upstream.example.com" + context.getRequestPath())
      .header("Authorization", context.getHeader("Authorization"))
      .build()
  ).execute();

  return Results.status(upstreamResponse.code())
    .contentType(upstreamResponse.header("Content-Type"))
    .renderRaw(upstreamResponse.body().string());
}

API Reference

RequestBuilder

Method	Description
.url(url)	Set the request URL
.header(name, value)	Add a header
.get()	Set method to GET (default)
.post(body)	Set method to POST with body
.put(body)	Set method to PUT with body
.patch(body)	Set method to PATCH with body
.delete()	Set method to DELETE
.delete(body)	Set method to DELETE with body
.build()	Build the Request object

RequestBody

Method	Description
RequestBody.create(data, mediaType)	Create a body from string + MediaType

MediaType

Method	Description
MediaType.parse(mimeType)	Parse a MIME type string

Response

Method	Description
.code()	HTTP status code
.isSuccessful()	true if status is 2xx
.body().string()	Response body as string
.header(name)	Get a response header