Tutorial: How to backup and restore Custom API rulesets

Step 1: Retrieve your rules

We'll start by retrieving all your current custom rules. Assuming your token is "MYTOKEN", visit the following URL in the browser: https://api.diffbot.com/v3/custom?token=MYTOKEN

This should produce a screen like the following:

This is a simple JSON file (JSON is a specific data format) which contains a list of all your custom API rules. The collapsed rules ({<->} in the image) are all different rules, but collapsed in the browser’s UI to make it more obvious that there are a lot of them. The code is made pretty with the help of this JSON viewer Chrome Extension.

Step 2: Save the file

To back up your rules, simply save this file somewhere onto the hard drive or your cloud storage with CMD/CTRL+S or File -> Save As. Make sure the file’s extension is .json, so for example myRules.json.
You can now store this file somewhere for later use. Alternatively, if you’re making changes to the rules make them and then save the file.

Importing the rules

So how do we use this file?

Using a handy tool like Postman, you would do the following:

In a new request tab, you would enter the API URL: https://api.diffbot.com/v3/custom?token=MYTOKEN. You can replace MYTOKEN with any token to which you want to upload the rules – does not have to be the one from which they were originally downloaded.

Switch the method to POST

In the "Body" tab, choose wither raw or binary. If you choose binary, then click on Choose Files and select the .json file we created earlier. If you choose raw, copy and paste that file’s content into the text area.

Finally, under the Headers tab, add Content-Type as the key, and application/json as the value, so that Diffbot knows to expect JSON content.

Press Send. This will upload the new rules into your token. You’ll get a response back that’s something like this:

{
  "hashes":
    [
      "507a31ce",
      "ax7n3sa1",
      "z992ns6c"
    ]
  }

These hash values are just IDs of the rules that were updated and can be safely ignored (or saved for reference later to update individual rulesets). The token you used will now have the rules you uploaded, along with any customizations.