This page explains how to use the REST API to programmatically generate data without having to use the UI.
The API was added in 3.2.0 to allow you to generate your data programmatically by calling a REST endpoint, instead of having to use the interface. The API is pretty basic: there's no user authentication and there's a simple on/off setting to allow it to be called. That's pretty much it! Go simplicity! This page explains how it all works: how to enable the API and how you can construct your requests to generate exactly what data you need.
Please note: the API is only available for your own installations. It's not available through the generatedata.com website due to bandwidth constraints.
The API is disabled by default. To enable it, first install the
script then edit your settings.php file (found in the root folder of where you installed it)
and add the following line:
$apiEnabled = true;
Once this is done, open up the following URL in your browser: http://yoursite/api/v1/data (you'll
need to replace the yoursite bit with whatever URL is appropriate. If it's working properly,
you should see the following:
{
"error": "Sorry, this endpoint only accepts POST requests. Please see the help documentation."
}
It's already whining at you! So far so good!
Now for the fun stuff! The API works by allowing you to POST JSON content to the /api/v1/data endpoint. The JSON content contains all the settings needed to generate the content you want. It's the JSON equivalent of using the UI.
Quite honestly, I couldn't care less. I've always found REST an adequate-at-best set of guidelines, so believe me I'm not losing any sleep over this. The problem was that the range of settings offered by the generatedata UI is vast. Offering the same functionality via REST ruled out passing all the info via the query string since the URLs would become far too long. So instead, "REST Best Practices" (i.e. "REST Least Awful practices") says you should use a POST. Sure.
So! As I was saying, you need to POST some JSON content in the body of the request to the /api/v1/data endpoint. The top-level JSON properties are of the following form:
{
"numRows": N,
"countries": [],
"rows": [
// list of Data Types hear, each
],
"export": {
// export settings here
}
}
numRows: (required). The number of rows to generate.countries: (optional). An array of country slugs. These correspond to the Country
plugins section within the UI. To find the available country slugs, take a look at the folders in the
/plugins/countries. In those folders, each Country plugin has a [Country].class.php
file. At the top of those files, there's a countrySlug setting - that's the string value
you'll want to use.rows: (required). This is where you define what data you actually want to generate.
This is an array of objects, each object needs to be of the following form:
{
"type": "DataTypeFolderName",
"title": "My title",
"settings": {
// ...
}
}
type: (required). The folder name of the Data Type you want to use.title: (required). the label for the field. Depending on your Export Type, this will be used
for things like the XML node name, database column name, JSON property name, etc. settings: (optional). This object contains any arbitrary settings that belong to the
Data Type. Each Data Type is unique and has 0-N settings. For details about the available settings for each
Data Type, check out the README files section below.export: (required). This object specifies what format you want your generated data to be in.
In other words, it targets a particular Export Type. Structurally it looks very much like the Data Type object:
{
"type": "ExportTypeFolderName",
"settings": {
// ...
}
}
type: (required). The folder name of the Export Type you want to use.settings: (optional). This object contains any arbitrary settings that belong to the
Export Type. Like with Data Types, every Export Type is unique and has 0-N settings. For details about
the available settings for each Data Type, check out the README files section below.
Since generatedata.com is really just an engine designed to be extended, the vast bulk of the work being
done to generate the data is done by plugins: Data Types and Export Types. The API is made possible by
getting all plugins to be well defined. Any plugin that offers one or more custom settings defines a
schema.json file containing a schema of those settings.
All Data Types and Export Types have their own README.md files containing documentation about
how they can be called via the API. They all contain example JSON that you can POST to your API endpoint. This
should greatly help you get up to speed quickly! To find the READMEs, just browse on github to the appropriate
plugin folder. For example:
If something isn't clear, or you feel it's incomplete either create a github issue, or just fork the project and fix the doc yourself. At the time of writing (Jan 2015), the doc is pretty complete, and I'll endeavor to keep it up to date.
Here's a full example in PHP using Curl. It generates 100 lines of JSON, containing 5 types of data: a first name, last name, email address, random password and US zipcode. Note that you'll need change the URL for your own installation.
require_once("library.php");
$json =<<< END
{
"numRows": 100,
"rows": [
{
"type": "Names",
"title": "First Name",
"settings": {
"placeholder": "Name"
}
},
{
"type": "Names",
"title": "Last Name",
"settings": {
"placeholder": "Surname"
}
},
{
"type": "Email",
"title": "Email"
},
{
"type": "AlphaNumeric",
"title": "Random Password",
"settings": {
"placeholder": "LLLxxLLLxLL"
}
},
{
"type": "AlphaNumeric",
"title": "US Zipcode",
"settings": {
"placeholder": "xxxxx"
}
}
],
"export": {
"type": "JSON",
"settings": {
"stripWhitespace": false,
"dataStructureFormat": "simple"
}
}
}
END;
$url = "http://yourpath/api/v1/data";
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $json);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
I've included a lot of (hopefully useful) error handling for the API to provide human-friendly feedback on what's gone wrong. I'll just jot down a few notes here.
The most basic error is a JSON syntax error. That'll yield the following error:
{"error":"API_INVALID_JSON","error_details":"Syntax error (JSON_ERROR_SYNTAX)"}
Unfortunately the JS validator being used doesn't contain any more info than that. So if you run into this problem go online and find a JS validator like JSONLint.com.
The errors here are super clear. It tells you exactly where the error occurs and what type of error is occurring. For example:
{
"error": "API_INVALID_DATA_TYPE_JSON",
"error_details": "Invalid Data Type JSON `settings` content passed",
"validation_error": "Missing required property: placeholder",
"location": "index 1 of the `rows` array",
"data_type":"AlphaNumeric"
}
Hopefully these sort of errors will be easily located based on the supplied errors. If not, let me know!
Create an issue on github. That's by far the best way to reach me - and others - who may be able to respond.