Offline RandomAPI (OfflineAPI) is an NPM module that you can install on your own machine to generate your APIs locally. Your own instance or instances of the RandomAPI Generator run locally on your computer (on port 61337 by default) and can be accessed in the same way as you access RandomAPI currently.

Why?

If latency, uptime, and speed are big concerns, OfflineAPI is perfect for you! You also won't need to compete with other users in your tier for resources on the RandomAPI servers during times of heavy load, and if you are traveling or somewhere without internet and need your random data, that won't be an issue either!

So what's the catch?

OfflineAPI is currently only available for premium accounts. In the future, this feature may expand to standard accounts, but for now, it's exclusive to premium users.

Alright you've got me sold, how do I use it?

Since RandomAPI runs on Node.js, the Generator naturally runs on Node.js as well. Make sure that you have Node and NPM installed on your machine.

Next, install the OfflineAPI module globally by running
npm install randomapi -g

Since OfflineAPI is a CLI script, we highly recommend installing it globally so you can access it from your terminal with randomapi.

After OfflineAPI finishes installing, it'll automatically launch the RandomAPI Generator in the background as a daemon on port 61337. You can run randomapi now if you would like to see the available commands.

At the time of writing this, there are currently some issues with getting the generator to run in the background on Windows. It currently opens up a new console window that you'll have to keep running in order for the generator to run. For now, you'll have to just minimize the window until we have an update for Windows. OS X and Linux users should be unaffected.

Next, we have to create an authToken on RandomAPI in order to authenticate your account with the server to sync your APIs, Lists, and Snippets.

Login to your RandomAPI account, go to settings, and then click on Offline RandomAPI. Or, you can click here if you want to be lazy :)

Your screen should look like this

Click on create new token and give your token a name and give your account password to authenticate yourself.

You will receive an authToken after you submit the form. Make sure that you copy this token now, you won't be able to see it again after you leave the page.

Next, go back to OfflineAPI and type randomapi login.

Give your username and the authToken we just generated to link your offline account with RandomAPI.

authTokens are linked to your account and can not be used with other accounts. They are also one time use.

If all goes well, you should get this screen:

If you are on Windows and the prompt doesn't reappear after you login, press CTRL-C to exit

Congratulations, your account and computer are now linked with your RandomAPI account!

Next, we need to sync with the RandomAPI server. Type randomapi sync to run the sync operation. After the operation completes, the RandomAPI server will automatically restart to load in the latest changes.

Type randomapi ls to view the APIs that are currently available locally.

Let's generate the Geocaching API demo that we made in this blog post.

randomapi gen 3

Notice how I ran 3 instead of typing out pgfznwxq. The CLI references the ordering of the APIs when you run the ls command for convenience.

Now how do you pass parameters like on the web version of RandomAPI? Just pass the parameters as a comma delimited list as the next argument.

randomapi gen 3 results=2,fmt=csv,seed=a

If you want to use the generator in the browser, you are free to do that as well!

Make sure that you use & in your parameters and the actual ref id in the browser

You can also access the same URL in any http library like curl or httplib in Python!

Snippets are also useful for organizing your code/APIs. If you use a piece of code often in many of your APIs, you could make a private snippet and then reference the snippet in your APIs to save space and make your code more readable.

From this

api.phone = phoneNum();

function phoneNum(format) {  
  format = format || "(xxx) xxx-xxxx";
  return String(format).split('').map(digit => {
    return digit === 'x' ? random.numeric(0, 9) : digit;
  }).join('');
}

To this

const phoneNum = require('~phoneNum');

api.phone = phoneNum();  

To make the above snippet, I made a new snippet called "phoneNum" and assigned my function to the variable snippet. Snippets are coded in basically the same way as a normal API except for these key differences:

• Objects are attached to the snippet object instead of the api object.
• Only Global Snippets can be used in your snippet. You can't require other snippets from your snippet.
• Snippet names must be unique in regards to your account (you can't have two snippets named "phonenum" for example).
• Only inline lists can be used in your API.

snippet = function(format) {  
  format = format || "(xxx) xxx-xxxx";
  return String(format).split('').map(digit => {
    return digit === 'x' ? random.numeric(0, 9) : digit;
  }).join('');
};

In the phone number example above, I attached my function directly to the snippet object kind of like what we did at the end of the What is an API blog post. But, you also have the option to attach multiple functions to a snippet as different properties. You can then access those snippet functions using their property names.

mysnippet

snippet.a = function() {  
    return "a";
};

snippet.b = function() {  
    return "b";
};

snippet.randomHexLetter = function() {  
    return list(['a', 'b', 'c', 'd', 'e', 'f']);
};

This snippet is pretty useless, but you can imagine the power that snippets have when used in conjunction with other snippets in your API.

To access the snippet functions above, you'd use the require function.

const mysnippet = require('~mysnippet');

api.a = mysnippet.a();  
api.b = mysnippet.b();  
api.hex = mysnippet.randomHexLetter();  

{
  "a": "a",
  "b": "b",
  "hex": "d"
}

You can also access snippets directly from the require function if you only need to use it once.

api.a = require('~mysnippet').a();  

Test out the final result of this demo API

First, let's create a new API. To do this, click on "New API" from the side navbar, give your API a name, and then click "Add new API". This'll take you to the API editor.

The API editor is split into two parts: a code editor on the left and a live preview on the right. The live preview will automatically execute your API code and show the results of your API code whenever it detects a change. You can also click Test API if you want to manually generate a new result.

After looking at some geocaching websites, it looks like these are some of the most common properties that a geocaching website would need.

• Name of the spot
• Creator's username
• Rating
• Favorites
• Number of visits
• Difficulty
• Terrain
• Size
• Date created
• Date updated
• Coordinates

For the Geocache name, we are going to generate a very basic name consisting of adjectives and nouns.

api.name = trailname();

function trailname() {  
    let trails     = ["trail", "path", "route", "stream", "walkway", "beaten path", "footpath"]
    let adjectives = ["dusty", "old", "scenic", "historic", "shady", "sunny"];
    let colors     = ["red", "orange", "yellow", "green", "blue", "indigo", "violet"];

    let combos = [
        [colors, trails],
        [adjectives, trails],
        [colors, adjectives, trails]
    ];

    let trailname = "";
    list(combos).forEach(part => trailname += " " + capitalize(list(part)));
    return trailname.trim();

    function capitalize(str) {
        return str.charAt(0).toUpperCase() + str.slice(1);
    }
}

{
  "name": "Violet Dusty Trail"
}

So now we have a name, but that trail function generator is kind of long and looks messy in our API. We are going to move the trailname function to a snippet since we may use it later on in other APIs and it'll clean up our code a bit. You can read more about implementing snippets here.

Here's what our API looks like now with our new trailname snippet.

const trailname = require('~trailname');  
api.name        = trailname();  

Next, we are going to generate the geocache creator's username. We are to use the Faker.js global snippet for this field as well as for generating the coordinates for our geocache.

...
const faker     = require('faker'); // Faker.js library  
api.username    = faker.internet.userName();  
...

{
  "username": "Dewayne75"
}

Let's knock a few more properties out of the way with the random.numeric and list function. Rating, favorites, number of visits, difficulty, and terrain will all take numeric values for star ratings and pure numbers for favorites and number of visits. We will also try and make the values more realistic by basing values like favorites and visits off of previously calculated values.

...
api.rating     = random.numeric(0, 50) / 10;  
api.favorites  = Math.ceil(api.rating * random.numeric(1, 15));  
api.visits     = api.favorites * random.numeric(1, 15)  
api.difficulty = random.numeric(1, 5);  
api.terrain    = random.numeric(1, 5);  
api.size       = list(['mini', 'small', 'medium', 'big', 'large']);  
...

{
  "rating": 2.9,
  "favorites": 41,
  "visits": 369,
  "difficulty": 2,
  "terrain": 4,
  "size": "large"
}

For date created and date updated, we'll take advantage of the moment library to provide readable formatting.

...
const moment = require('moment');

// Created 30 - 900 days ago
let created = timestamp() - 86400 * random.numeric(30, 900);

// Moment accepts timestamps in milliseconds
api.created = moment(created * 1000).format('LL');

// Updated date will be before the present but after the creation date
let updated = timestamp() - random.numeric(0, timestamp() - created);  
api.updated = moment(updated * 1000).format('LL');  
...

{
  "created": "July 25, 2015",
  "updated": "March 26, 2016"
}

And finally, let's use the Faker.js library again to generate a random set of coordinates for the geocache.

api.coords = `${faker.address.latitude()} ${faker.address.longitude()}`;  

{
    "coords": "40.7013 15.9303"
}

And we are finished! Here is the final API code (without the snippet so you can copy and paste directly) and an example of the results that it generated.

Call the API directly yourself

const faker  = require('faker'); // Faker.js library  
const moment = require('moment');

api.name       = trailname();  
api.username   = faker.internet.userName();  
api.rating     = random.numeric(0, 50) / 10;  
api.favorites  = Math.ceil(api.rating * random.numeric(1, 15));  
api.visits     = api.favorites * random.numeric(1, 15)  
api.difficulty = random.numeric(1, 5);  
api.terrain    = random.numeric(1, 5);  
api.size       = list(['mini', 'small', 'medium', 'big', 'large']);

// Created 30 - 900 days ago
let created = timestamp() - 86400 * random.numeric(30, 900);

// Moment accepts timestamps in milliseconds
api.created = moment(created * 1000).format('LL');

// Updated date will be before the present but after the creation date
let updated = timestamp() - random.numeric(0, timestamp() - created);  
api.updated = moment(updated * 1000).format('LL');

api.coords = `${faker.address.latitude()} ${faker.address.longitude()}`;

// Snippet code
function trailname() {  
    let trails     = ["trail", "path", "route", "stream", "walkway", "beaten path", "footpath"]
    let adjectives = ["dusty", "old", "scenic", "historic", "shady", "sunny"];
    let colors     = ["red", "orange", "yellow", "green", "blue", "indigo", "violet"];

    let combos = [
        [colors, trails],
        [adjectives, trails],
        [colors, adjectives, trails]
    ];

    let trailName = "";
    list(combos).forEach(part => trailName += " " + capitalize(list(part)));

    return trailName.trim();

    function capitalize(str) {
        return str.charAt(0).toUpperCase() + str.slice(1);
    }
}

{
  "name": "Indigo Dusty Path",
  "username": "Henry_Schaden",
  "rating": 1.8,
  "favorites": 15,
  "visits": 45,
  "difficulty": 4,
  "terrain": 2,
  "size": "mini",
  "created": "September 11, 2015",
  "updated": "November 15, 2015",
  "coords": "38.3802 -23.2441"
}

The getVar function can access variables such as fmt, key, ref, etc. as well if you need to determine the format your API was requested in, etc.

You can also access some internal RandomAPI Generator variables such as numericSeed which is the internal seed that the generator is using for the current job it is generating. This could be especially useful if you are using a custom snippet or global snippet that has a seeding property you'd like to set (which we recommend so that the generator's seed and snippet's seed match each other and respect any custom seed values you might provide in your URI).
Or if you need a number on the [0,1) real interval, you can use the special prng() function that will return a number directly from the Mersenne Twister module that the generator is using.

api.seed    = getVar('seed');  
api.numSeed = getVar('numericSeed');  
api.format  = getVar('fmt');  
api.key     = getVar('key');  
api.ref     = getVar('ref');  
api.prng    = prng();  

{
  "seed": "7583c1fdce1943f4",
  "numericSeed": 4200665598,
  "format": "pretty",
  "key": "ABCD-1234-EFGH-5678",
  "ref": "1234abcd",
  "prng": 0.9772644529584795
}

Let's make a simple math API for example. In this example, we are basically generating 2 numbers and then performing an operation on them. By default, the program will add the 2 numbers together and then assign the sum to a property called add. In this example, the user can completely change the functionality of this API by changing the operation that is performed by sending in an operation value through the URI.

If the operation passes our validation check, the program will end up using a different operator and result with completely different output.

// Fetch the value sent in through the operation GET variable
let operation = getVar('operation');

// Accepted operations that we will check against
let validOperations  = ["add", "sub", "mul", "div", "mod"];  
let operationSymbols = [ "+",   "-",   "*",   "/",   "%" ];

// Default value
let useOperation = "add";

// Only use sent in operation if it is in our list of valid operations.
let index = validOperations.indexOf(operation);

if (index !== -1) {  
    useOperation = operation;
} else {
    index = 0; // Add is 0.
}

api.num1 = random.numeric(1, 25);  
api.num2 = random.numeric(1, 25);

api[useOperation] = eval(`${api.num1}${operationSymbols[index]}${api.num2}`);  

/api/1234abcd?key=...&operation=sub

{
  "num1": 15,
  "num2": 6,
  "sub": 9
}

For this example, the getVar result was fairly simple but it is easy to see how you can configure your API to have completely different behavior depending on the input that is sent in.

Let's use the Pokemon Game Clone that I am working on as an example and use case for the list.

When you upload a list, you'll be given a reference id. This unique identifier is what you'll use to specify the list you want to use in your API. Only your account has access to the contents of this list.

api.pokemon = list('sx9kqznu');  

{
  "pokemon": "Vulpix"
}

By default, the list function will choose a random item from the list. You can however specify a line number as the 2nd parameter if you'd like. For my Pokemon Generator, it'd be nice to have a separate id variable generated and then I could use that value to choose the proper line number/pokemon from the list.

api.id = random.numeric(1, 151);  
api.pokemon = list('sx9kqznu', api.id);  

{
  "id": 112,
  "pokemon": "Rhydon"
}

As hinted at from before, you can also send an array directly to the list function. The 2nd parameter is also available if you use the list this way, but keep in mind that the index is zero-based for arrays. Let's give the generated pokemon a gender now. It'd be overkill to upload a text file only containing "male" and "female", so let's send in an array!

api.id = random.numeric(1, 151);  
api.gender = list(['male', 'female']);  
api.pokemon = list('sx9kqznu', api.id);  

{
  "id": 115,
  "gender": "female",
  "pokemon": "Kangaskhan"
}

http://beta.randomapi.com/api/1234abcd?key=ABCD-1234-EFGH-5678

In the RandomAPI world, an API can be thought of as the Javascript source code that instructs the generator how to generate the random data you want.

const faker = require('faker');

api.user     = faker.name.findName();  
api.userID   = random.special(4, 5);  
api.password = random.special(3, 8);  

{
  "user": "Mireille Homenick DVM",
  "userID": "10057",
  "password": "Vq8EqJr0"
}

A RandomAPI API is an API (say that 3x fast) in the sense that you can provide input through the GET variables you send in your URI (?mode=1&list=23) and receive output that is affected by those inputs. But other than that, it is completely different from your run of the mill API.

With that definition out of the way, let's get into some technical details regarding APIs.

Every API has an implicit API object appropriately named api. All of the data that you want returned to you when you call your API must be attached to this object as a property. In this example, only the variable a will be returned since it is attached to the api object.

// Local variables. If you want to do complicated operations before attaching the result to the api object, local variables can be helpful

let num1 = 4;  
let num2 = 20;  
let a = num1 * num2;  
let b = 5;

// Attach a to the api object.
api.a = a;  

{
  "a": 80
}

You can also redefine the API object by assigning properties directly if you wish.

api = {  
  a: 5,
  b: 6
};

{
  "a": 5,
  "b": 6
}

You can even set the api object to something other than an object.

api = `Billy is ${random.numeric(13,21)} years old and likes the color ${list(['red', 'orange', 'yellow', 'green', 'blue', 'indigo', 'violet'])}`  

"Billy is 17 years old and likes the color green"

It's been about 2 years since I released the the old PHP version of RandomAPI. It was a cool idea that had potential, but looking back, there were many features that weren't fully fleshed out and the generation technology itself could have been much better. Instead of trying to reinvent the wheel with my own custom tailored "programming language" and "parser", I should have gone the route of using a language that was easy to learn and widely available and familiar.

That's what RandomAPI 2.0 is!

A complete rewrite from the ground up in Node.js/Express, RandomAPI 2.0 promises to bring some much needed speed and feature improvements along with a much cleaner and less cluttered design.

Old Site
New Site

Instead of using an esoteric, homemade language, Vanilla Javascript is fully supported! Along with speed improvements, something that is familiar, easy to learn, and powerful improves the RandomAPI experience in every way.

Along with all of these huge improvements, RandomAPI 2.0 introduces a new feature that I think will be a big hit: Snippets. Snippets are user defined pieces of code that can be included in an API using the familiar require syntax in Node.js (read about it more here). If you've made a function or data generator that you think would be beneficial for other users, you can publish your snippet for others to import into their APIs! Think of it like NPM for Node.js modules.

And speaking of node modules, "global snippets" are included as well. Global snippets, a.k.a. node modules, are normal modules that you would require in a standalone node program. Some global snippets like Faker and Moment can be required into your APIs as well. Overtime, more modules will be added that can be helpful for your APIs. If you have any suggestions, feel free to send us a message!

And that's about it for now! The purpose of this blog will mainly be for updates as well as more in-depth tutorials than what the documentation provides. Thanks for reading!

- Keith