RESTful APIs With DreamFactory

2023-07-14

The Problem

Most of the programming I have done over the past twenty years has been writing boring line of business applications and it's probably what any programmer reading this also does most of the time. There are lots of tools in the 'low code' area but they're usually targeted at analysts and managers rather than developers.

I wanted something compliant with the jsaonapi.org specification and although there are things out there like LoopBack which are mature and well supported they all take a bit of setting up.

I wanted to be able to point to a data source and convert it into a compliant RESTful API but I struggled to find anything that did this out of the box. PostgREST is a good example of something that does what I want and is an excellent project but it only works with PostgreSQL. I do a lot of .NET coding and I recently discovered JsonApiDotNetCore which looks promising but it's relatively new.

Eventually I came across DreamFactory which is both mature and well supported. There is some setting up but it effectively gives you a full API for any database with minimal effort. In fact it appears to be quite a powerful tool and I've barely scratched the surface.

DreamFactory Setup

For this example I'm going to use SQLite but most well known databases are supported along with various other service types. The database I'm using can be downloaded directly from here. It's a copy of the famous Northwind database familiar to anyone who remembers programming with MS Access back in the day! No setup for the database is required but you will need PHP installed.

Once the database is downloaded and ready you'll need a copy of DreamFactory which we'll get using Git:

git clone https://github.com/dreamfactorysoftware/dreamfactory

Once the repo is cloned cd into the directory:

cd dreamfactory

You'll also need PHP's Composer installed for the next step:

composer install

Once that's done cd into the public directory:

cd public

Now we're ready to run DreamFactory which can be done running the following:

php -S localhost:8000

Create Administrator

If you now browse to localhost:8000 you should see a prompt to create an administrator:

Fill the details out similar to as shown above and click the CREATE button. You will be redirected to the main dashboard:

Create Service

Click the Services tab along the top and the click the Create button. Select the correct Service Type and fill out the details as shown below:

Click the Next button and then enter the correct database path for the Northwind SQLite database that was downloaded earlier. Your path will be different to mine:

Click Save and you should see your newe service added to the list of managed services:

Create Application

Next click the Apps tab along the top and click the Create button to create a new application. Fill out the details as shown below:

Click Save and the application will be added to the list of managed applications:

Create Role

Click the Roles tab along the top and then click the Create button to create a new role. Fill out the Basic section as shown below:

Click Next and then fill out the Access section as shown below. Make sure to select the service created in the previous section and select all available HTTP verbs under Access:

Click Save and the role will be added to the list of managed roles:

Create Service User

Finally click the Users tab along the top and then click the Create button to create a new user. Fill out the Basic section as shown below:

Click the Roles section and select the role created in the previous step.

Click Save and the new user will appear in the users list:

That's it, you now have a fully managed RESTful API for your database! To test it click the API Docs tab along the top which will then present you with a list of options:

Potential Gotchas

There are a couple of potential gotchas to look out for. It might be necessary to add an entry for CORS. This is found by selecting the Config tab along the top. Below is an example of what the entries should look like:

You will also require an API Key for the application. This key is generated when the application is created and can easily be found with the rest of the application's details:

Testing The API

There's lots of options for testing but the simple example below retrieves the records from the Employees table:

Click execute and the records are returned. The response also provides an example to use with Curl:

Conclusion

There's a lot more to explore with DreamFactory. It appears to be quite powerful and you get a lot for free. There is also a paid option which has lots of other goodies but I was just looking for something to create a RESTful API out the box and this ticks all those boxes. I'm surprised it's not more popular!