API

This page explains how to use the REST API to programmatically generate data without having to use the UI.

Introduction

The API was added in 3.2.0. All Data Types and Export Types were updated for compatibility, so you can now generate custom data by calling a REST endpoint. At this stage the API is pretty basic: there's no user authentication and the API is either enabled or not. That's pretty much it. This page explains how it all works: how to enable the API and how you can construct your requests to retrieve precisely what data you need.

Please note: the API is only available for your own installations. It's not available via the main generatedata.com website mainly due to bandwidth constraints.


How to Enable

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."
}

So far so good!


How the API Works

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.

POST, to GET something?! But this isn't RESTful!

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.

Now back to regular scheduled programming

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.


Examples / README files

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.


Error Handling

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.

Syntax error

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.

Missing / Invalid Data Type / Export Type settings

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!


Questions / Bugs?

Create an issue on github. That's by far the best way to reach me - and others - who may be able to respond.