Skip to main content

​
Overview

The httpGetJson utility function provides a simple way to make HTTP/HTTPS GET requests and retrieve JSON data or other content types. It handles both HTTP and HTTPS protocols automatically and includes built-in error handling.

​
Function Signature

function httpGetJson(
  url: string,
  options?: {
    suppressErrors?: boolean;
    headers?: HeadersObject;
    agent?: any;
  }
): Promise<any>

​
Parameters

​
url
string
required
The complete URL to fetch data from. Must include the protocol (http:// or https://)
​
options
object
Optional configuration object

​
Return Value

Returns a Promise that resolves with:
  • Parsed JSON object if the content type is application/json (default)
  • Raw string data if a different content type is specified via headers.expectedContentType
  • undefined if an error occurs and suppressErrors is set to true
  • Rejected promise with an error if the request fails and suppressErrors is false

​
Usage Examples

​
Basic JSON Request

import { httpGetJson } from '@scullyio/scully';

const data = await httpGetJson('https://api.example.com/data');
console.log(data);

​
With Error Suppression

import { httpGetJson } from '@scullyio/scully';

// Returns undefined if the request fails instead of throwing
const data = await httpGetJson('https://api.example.com/optional-data', {
  suppressErrors: true
});

if (data) {
  console.log('Data received:', data);
} else {
  console.log('Using fallback data');
}

​
Custom Headers and Content Type

import { httpGetJson } from '@scullyio/scully';

// Fetch XML data instead of JSON
const xmlData = await httpGetJson('https://api.example.com/feed.xml', {
  headers: {
    expectedContentType: 'application/xml',
    'User-Agent': 'Scully Bot'
  }
});

​
With Custom Agent

import { httpGetJson } from '@scullyio/scully';
import { HttpsProxyAgent } from 'https-proxy-agent';

const agent = new HttpsProxyAgent('http://proxy.example.com:8080');

const data = await httpGetJson('https://api.example.com/data', {
  agent
});

​
Error Handling

The function validates responses and rejects with errors in the following cases:
If the response status code is not 200, the promise is rejected with an error message:
Request Failed. Received status code: {statusCode} on url: {url}
If the response content type doesn’t match the expected type, the promise is rejected:
Invalid content-type.
Expected {expectedContentType} but received {responseContentType}
on url: {url}
The default expected content type is application/json.
Network-level errors (connection refused, DNS errors, etc.) are caught and either:
  • Rejected if suppressErrors is false (default)
  • Resolved with undefined if suppressErrors is true

​
HTTPS Handling

When making HTTPS requests, the function automatically sets NODE_TLS_REJECT_UNAUTHORIZED to '0', which disables SSL certificate validation. This is intended for development purposes only.A warning message is displayed once per process:
NOTICE:
****************************************************************************************
  This is a development tool for Scully applications.
  You can ignore the warning (TLS) or run scully with --no-warning
****************************************************************************************

​
Common Use Cases

Fetch API Data

Retrieve JSON data from REST APIs during the Scully build process

Content Retrieval

Fetch remote content like RSS feeds, XML sitemaps, or configuration files

Plugin Development

Use in custom Scully plugins to fetch data for route generation

Optional Resources

Load optional resources with error suppression for graceful fallbacks

Route Discovery

Learn how to use httpGetJson in route discovery

Router Plugins

Create router plugins that fetch remote data

​
Source Code

Location: libs/scully/src/lib/utils/httpGetJson.ts:14

Build docs developers (and LLMs) love

Get started for freeTalk to us