Getting Started with the DreamFactory API

In this blog post, we’ll show you how to make some simple API calls with the DreamFactory API. The API requires SSL3. If you plan on making requests from cURL, or your native SDK, make sure you are using version 3.

For example, in cURL:

curl -3 url

Your “api key” to talk to our API is your App Name as defined in the DreamFactory Administration Console. For each request, you can:

1. Append app_name=yourappname to the query string or
2. Send a request header called X-DreamFactory-Application-Name with the value of your app name

Working with User Sessions (/user/session)

Authentication 

If your application is not part of the guest user’s role, then access to any service or data components will require authentication.

To authenticate a user, simply POST a JSON string to /user/session that takes on the following format:

{“email”:”email_value”, “password”:”password_value”}

For example:

curl -k -3 -X POST https://dsp-yourdsp.cloud.dreamfactory.com/rest/user/session -H "X-DreamFactory-Application-Name: todojquery" -d "{ "email" : "slimjim@foo.com", "password" : "foo" }"

This will return one of four responses:

• A 201 as the session has been created. In the response, you’ll see a session_id has been created. Very Important: For all future requests to the API, you’ll need to pass this value as a new request header called X-DreamFactory-Session-Token

• A 401 if the login information did not match any records on the backend

• A 403 if CORS has not been enabled and you’re trying to use the API cross-domain

• A 400 if you did not include your API Key (App Name)           

You can append app_name=yourappname to the query string or send a request header calledX-DreamFactory-Application-Name.

To refresh a user’s session, or just check to see if they have one, simply do a GET on /user/session.

Using our local DB service (/db/[table name]/[id])

As you’d expect, getting to your data is just a URL away. 

Retrieving Data 

To access any table available to your role, use the following format. In this example, we make a request for the todo table:

GET https://dsp-yourdsp.cloud.dreamfactory.com/rest/db/todo

For example:

curl -3 https://dsp-yourdsp.cloud.dreamfactory.com/rest/db/todo?app_name=todoangular

Important Note: Don’t forget your X-DreamFactory-Application-Name, and if a session is required, your X-DreamFactory-Session-Token header.

If you are doing this cross-domain, enable CORS in the System Configuration section of the DreamFactory Administration Console.

Filtering Data

To filter data by field, add an additional url param (filter) as follows. In this example, we make a request for the todo table:

https://dsp-yourdsp.cloud.dreamfactory.com/rest/db/todo?app_name=todoangular&filter=complete=true

This API call returns all todo items that are complete.

Attaching Schema

To attach your table’s schema as metadata in the response, just add a url param, like this:

GET https://dsp-yourdsp.cloud.dreamfactory.com/rest/db/todo?include_schema=true

Important Note: Don’t forget your X-DreamFactory-Application-Name, and if a session is required, your X-DreamFactory-Session-Token header.

Enjoy!  If you have any issues, head over to https://dreamfactorysoftware.github.io