This add-on is operated by DreamFactory Software, Inc.

DreamFactory can generate APIs for a variety of databases, including PostgreSQL.

Last updated February 14, 2022

DreamFactory is the easiest way to automatically generate and secure REST APIs for a wide variety of data sources including PostgreSQL and MySQL, convert SOAP to REST, and aggregate disparate data sources through a single API response.

Adding DreamFactory to an application allows you to integrate any SQL, including Heroku Postgres, or NoSQL database, file storage system, or external HTTP or SOAP service and DreamFactory instantly generates a flexible, comprehensive, and fully documented REST API endpoint that’s ready to use.

DreamFactory is accessible via a REST API and has supported client libraries for almost every platform, including Java, Ruby, Python, Node.js, Clojure, Scala, PHP and Go.

Provisioning the add-on

DreamFactory can be attached to a Heroku application via the CLI:

$ heroku addons:create dreamfactory --app your-app-name
-----> Adding dreamfactory to sharp-mountain-4005... done, v18 (free)

After you provision DreamFactory, the following configuration vars is available in your app’s configuration:

1. DREAMFACTORY_INSTANCE_URL
2. DREAMFACTORY_ADMIN_EMAIL
3. DREAMFACTORY_ADMIN_PASSWORD

It contains the canonical URL used to access the newly provisioned DreamFactory service instance and root admin credentials. You can confirm this via the heroku config:get command:

$ heroku config:get DREAMFACTORY_INSTANCE_URL --app your-app-name
https://instance12345.apps.dreamfactory.com/

$ heroku config:get DREAMFACTORY_ADMIN_EMAIL --app your-app-name
admin@example.com

$ heroku config:get DREAMFACTORY_ADMIN_PASSWORD --app your-app-name
password

After you install DreamFactory, your application should be configured to fully integrate with the add-on.

Using the DreamFactory web-ui

The DreamFactory dashboard allows you to access the following features:

1. API Limits
2. Authentication & Authorization
3. Cache Services
4. CORS Configuration
5. CSV-to-REST
6. Database Services
7. Directory Services (AD, LDAP)
8. Dynamic Service Types
9. Email Services
10. File Storage Services
11. HTTP (Remote Web) Services
12. Live API Docs
13. Log Services
14. Lookups and System Variables
15. Push Notification Services
16. REST API
17. Role Access and Server-Side Filters
18. Server-Side Scripting
19. SOAP Services
20. System Resources

You can access the dashboard via the CLI:

$ heroku addons:open dreamfactory --app your-app-name
Opening https://addons-sso.heroku.com/apps/...

Alternatively you can visit the Heroku Dashboard and select the application in question. Select DreamFactory from the Add-ons menu.

Integrating services

By default, DreamFactory contains several configured services which you could use for your application:

• System Management - service for managing system resources
• Live API Docs - API documenting and testing service
• Local File Storage - service for accessing local file storage
• Local Log Storage - service for accessing local log storage
• Local SQL Database - service for accessing local SQLite database
• Local Email Service - service for sending emails
• User Management - service for managing system users

If you want to create new one, for example Heroku Postgres database service, follow the next steps:

1. Open DreamFactory web-ui.
2. Go to Services tab and click Create.
3. Select Database > PostgreSQL.
4. Fill Namespace, Label and Description fields.
5. Click Next.
6. Fill Host, Port Number, Database, Username and Password.
7. Scroll down to the end and click Save.

Namespace field value is used as a unique service identifier (service name) for access via REST API. Read more about the DreamFactory API here.

Label and Description field is used for you to recognize the service and what it does. Description is optional and you can skip it.

You can obtain the Host, Port Number, Database, Username and Password values from your database provider.

Once you have saved the service, you can access the API on the API Docs tab.

Creating API keys

DreamFactory will generate and manage API keys for you. Each API key is associated with a role-based access control, so let’s begin by creating a role.

Creating roles

DreamFactory uses roles to define access rights for an application or user. To send requests from your application to the DreamFactory service, you have to create a role with access to this service.

1. Open Roles tab.
2. Click Create.
3. Fill Name, Description fields and mark role as active.
4. Click Next.
5. Add access to the service using plus button at the right side.
6. Make sure that you selected allowed request verbs.
7. Click Save.

Creating apps

Every API key in DreamFactory is bound to the apps. If you want to create a new API key, then you have to create a new app.

1. Open Apps tab.
2. Click Create.
3. Fill Application Name, Description and select role for the app.
4. Mark app as active.
5. Select app location. If you are creating a service for a database, then most of all you have to choose No Storage Required.
6. Click Save.
7. Your API key available in Applications table.

Using with PHP

<?php

$cURLConnection = curl_init('https://your-instance-prefix.apps.dreamfactory.com/api/v2/your-service-name/_table/your-table-name');
curl_setopt($cURLConnection, CURLOPT_HEADER, 'X-DreamFactory-API-Key: api-key-from-previous-step');
curl_setopt($cURLConnection, CURLOPT_RETURNTRANSFER, true);

$apiResponse = curl_exec($cURLConnection);
curl_close($cURLConnection);

// $apiResponse - available data from the API request
$jsonArrayResponse = json_decode($apiResponse);

Using with NodeJS

const https = require('https');

https.get({
  host: "your-instance-prefix.apps.dreamfactory.com",
  path: "/api/v2/your-service-name/_table/your-table-name",
  protocol: "https:",
  headers: {
    'X-DreamFactory-API-Key': 'api-key-from-previous-step',
  },
}, (resp) => {
  let data = '';

  // A chunk of data has been received.
  resp.on('data', (chunk) => {
    data += chunk;
  });

  // The whole response has been received. Print out the result.
  resp.on('end', () => {
    console.log(JSON.parse(data));
  });

}).on("error", (err) => {
  console.log("Error: " + err.message);
});

Using with Java

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;

public class Main {

    public static void main(String[] args) throws IOException {
        URL obj = new URL("https://your-instance-prefix.apps.dreamfactory.com/api/v2/your-service-name/_table/your-table-name");
        HttpURLConnection con = (HttpURLConnection) obj.openConnection();
        con.setRequestMethod("GET");
        con.setRequestProperty("X-DreamFactory-API-Key", "api-key-from-previous-step");
        int responseCode = con.getResponseCode();
        System.out.println("GET Response Code :: " + responseCode);
        if (responseCode == HttpURLConnection.HTTP_OK) {
            BufferedReader in = new BufferedReader(new InputStreamReader(
                    con.getInputStream()));
            String inputLine;
            StringBuilder response = new StringBuilder();

            while ((inputLine = in.readLine()) != null) {
                response.append(inputLine);
            }
            in.close();

            // print result
            System.out.println(response.toString());
        } else {
            System.out.println("GET request not worked");
        }
    }
}

Troubleshooting

Logging

If you experience issues with some of the services, like SQL database connection or server-side scripting, please check the DreamFactory log file. It contains more information about system errors.

To access the logs you have to go to the Files tab. Then click on logs directory and open the dreamfactory.log file.

Clearing cache

When you change the settings of services, it is usually better to clear the system cache. Clear the cache using the DreamFactory Admin application by clicking the Config tab, then Cache menu option, and then clicking Flush System-Wide Cache.

Common errors

Please go to the DreamFactory Wiki to get more information.

Migrating between plans

Use the heroku addons:upgrade command to migrate to a new plan.

$ heroku addons:upgrade dreamfactory:newplan --app your-app-name
-----> Upgrading dreamfactory:newplan to sharp-mountain-4005... done, v18 ($49/mo)
       Your plan has been updated to: dreamfactory:newplan

Removing the add-on

You can remove DreamFactory via the CLI:

$ heroku addons:destroy dreamfactory --app your-app-name
-----> Removing dreamfactory from sharp-mountain-4005... done, v20 (free)

Before removing DreamFactory, you can contact us at support@dreamfactory.com to export your data.

Support

All DreamFactory support and runtime issues should be submitted via one of the Heroku Support channels. Any non-support related issues or product feedback is welcome at support@dreamfactory.com.

Additional resources

• DreamFactory website
• DreamFactory guide
• DreamFactory wiki
• DreamFactory forum