Java Client Guide

Use the built-in java.net.HttpURLConnection to call the Shorted API. No external libraries are required for basic usage.

Prerequisites

Java 11+
No external dependencies for basic HTTP

Authentication

Include your API key in the Authorization header as a Bearer token. Public endpoints work without authentication but have lower rate limits.

import java.net.*;
import java.io.*;

public class ShortedApiAuth {
    public static void main(String[] args) throws Exception {
        URL url = new URL(
            "https://shorts-uiekqxovma-km.a.run.app/shorts.v1alpha1.ShortedStocksService/GetTopShorts");
        HttpURLConnection conn = (HttpURLConnection) url.openConnection();
        conn.setRequestMethod("POST");
        conn.setRequestProperty("Content-Type", "application/json");
        conn.setRequestProperty("Authorization", "Bearer YOUR_API_KEY");
        conn.setDoOutput(true);

        String json = "{\"limit\": 10}";
        conn.getOutputStream().write(json.getBytes());

        BufferedReader reader = new BufferedReader(
            new InputStreamReader(conn.getInputStream()));
        String line;
        while ((line = reader.readLine()) != null) {
            System.out.println(line);
        }
    }
}

Example: Get Top Shorted Stocks

Retrieve the most heavily shorted stocks on the ASX, sorted by short interest percentage.

import java.net.*;
import java.io.*;

public class GetTopShorts {
    public static void main(String[] args) throws Exception {
        URL url = new URL(
            "https://shorts-uiekqxovma-km.a.run.app/shorts.v1alpha1.ShortedStocksService/GetTopShorts");
        HttpURLConnection conn = (HttpURLConnection) url.openConnection();
        conn.setRequestMethod("POST");
        conn.setRequestProperty("Content-Type", "application/json");
        conn.setDoOutput(true);

        String json = "{\"limit\": 10, \"offset\": 0}";
        conn.getOutputStream().write(json.getBytes());

        BufferedReader reader = new BufferedReader(
            new InputStreamReader(conn.getInputStream()));
        StringBuilder response = new StringBuilder();
        String line;
        while ((line = reader.readLine()) != null) {
            response.append(line);
        }

        System.out.println(response.toString());
    }
}

Example: Get Stock Details

Fetch detailed information about a specific stock by its ASX code.

import java.net.*;
import java.io.*;

public class GetStock {
    public static void main(String[] args) throws Exception {
        URL url = new URL(
            "https://shorts-uiekqxovma-km.a.run.app/shorts.v1alpha1.ShortedStocksService/GetStock");
        HttpURLConnection conn = (HttpURLConnection) url.openConnection();
        conn.setRequestMethod("POST");
        conn.setRequestProperty("Content-Type", "application/json");
        conn.setDoOutput(true);

        String json = "{\"productCode\": \"BHP\"}";
        conn.getOutputStream().write(json.getBytes());

        BufferedReader reader = new BufferedReader(
            new InputStreamReader(conn.getInputStream()));
        StringBuilder response = new StringBuilder();
        String line;
        while ((line = reader.readLine()) != null) {
            response.append(line);
        }

        System.out.println(response.toString());
    }
}

Error Handling

The API returns standard HTTP status codes. Rate limited requests return 429 with a Retry-After header. Always check the response status before parsing the body.

import java.net.*;
import java.io.*;

public class ShortedApiClient {
    private static final String BASE_URL = "https://shorts-uiekqxovma-km.a.run.app";

    public static String apiCall(String path, String body, String apiKey)
            throws Exception {
        URL url = new URL(BASE_URL + path);
        HttpURLConnection conn = (HttpURLConnection) url.openConnection();
        conn.setRequestMethod("POST");
        conn.setRequestProperty("Content-Type", "application/json");
        if (apiKey != null) {
            conn.setRequestProperty("Authorization", "Bearer " + apiKey);
        }
        conn.setDoOutput(true);
        conn.getOutputStream().write(body.getBytes());

        int status = conn.getResponseCode();

        if (status == 429) {
            String retryAfter = conn.getHeaderField("Retry-After");
            int delay = retryAfter != null ? Integer.parseInt(retryAfter) : 60;
            System.out.printf("Rate limited. Retrying in %ds...%n", delay);
            Thread.sleep(delay * 1000L);
            return apiCall(path, body, apiKey);
        }

        InputStream stream = status >= 400
            ? conn.getErrorStream()
            : conn.getInputStream();

        BufferedReader reader = new BufferedReader(new InputStreamReader(stream));
        StringBuilder response = new StringBuilder();
        String line;
        while ((line = reader.readLine()) != null) {
            response.append(line);
        }

        if (status >= 400) {
            throw new RuntimeException(
                "API error " + status + ": " + response);
        }

        return response.toString();
    }

    public static void main(String[] args) throws Exception {
        String result = apiCall(
            "/shorts.v1alpha1.ShortedStocksService/GetTopShorts",
            "{\"limit\": 10}",
            "YOUR_API_KEY"
        );
        System.out.println(result);
    }
}

All Endpoints

See the full API reference for all available endpoints, request/response schemas, and the interactive "Try It" panel.