API

The DreamFactory REST API is a RESTful implementation of the DreamFactory interface, allowing access to all services provisioned on a DreamFactory instance. Access is granted to everything when authenticated as an administrator, or based on the role access assigned to the user, or based on default role access assigned to each application for non-authenticated calls.

A great tool to help you learn the REST API is the Live API application, also known as "Swagger", included with every DreamFactory instance.

Layout

The layout of the typical DreamFactory REST API call can best be described as follows...

<verb> http[s]://<server-name>/api/v<api-version>/[<service-name>]/[<resource-path>][?<param-name>=<param-value>]

with the following breakdown for each part...

verb - The HTTP verb matching the use of the API call, see [Verbs](#verbs) section below.
server-name - The name or IP given to the installed web server that is running the DreamFactory instance.
api-version - This is the version number of the REST API, currently "2". Performing a GET here returns an array of available services when permissions allow.
service-name - The API name of the service you want to access. Performing a GET here on most of the native services will return an array of available resources.
resource-path - The optional resource path of the service. This path may include multiple sections divided by '/' as such to define the resource.
param-name - URL parameters that are available, which vary by service type, see [common](#common) ones below.
param-value - Values given for URL parameters. Note: Each value must be properly encoded.

Please check out the sections below and the Authentication and Authorization section before digging into the other sections of this documentation.

Verbs

The DreamFactory REST API adheres to the typical REST HTTP verbs like GET, POST, PUT, DELETE. The API also supports the PATCH verb. In certain services, HEAD and OPTIONS verbs may be supported as well. DreamFactory also supports HTTP verb tunneling discussed in more detail [here](#tunneling).

POST vs PUT vs PATCH

Verbs like GET and DELETE are pretty self explanatory, but the difference in the three P's as we call them, may not be as clear. In use of all three, posted data with the request is expected, except where noted.

POST - typically used to create a new resource and typically the response status is "201 Created" if successful.
PUT - typically used to update or replace an existing resource as a whole, i.e. the old resource is essentially replaced with the new resource. This has been around a while and heavily used in file-based situations. One place to note here is the use of NoSQL (i.e. no schema) records, where the whole record is replaced with new record.
PATCH - typically used to update only a part of an existing resource, i.e. new data or settings are merged into the existing resource, possibly overriding existing data or settings.

In some situations, upsert capabilities may exist where posted data may be used to update an existing resource if present or create a new resource altogether. In this case, it is up to the individual API to determine whether POST or PUT is used.

The Resource Wrapper

The DreamFactory API utilizes a resource wrapper, a string attribute surrounding an array of items, to help maintain consistency and ease of use when sending or receiving multiple items (i.e. resources, entities, records, lists). When a single item, or various parameters sent via payload (i.e. filters, etc) are sent or received, the wrapper is typically not used.

The wrapper is configurable, allowing the string used to be customized, or disabling the wrapper altogether (except in the event that an array of items along with metadata are present in the payload). The following configurations are found in the config/df.php file in the install directory.

always_wrap_resources - Boolean. Defaults to true. Wrapper is used on output and expected on input payloads where arrays of items are expected.
resources_wrapper - String. Defaults to "resource". Value of the wrapper string when used.

Common Headers & Parameters

Most of the common REST API options can be passed via HTTP headers or URL parameters. While these are "commonly" used, they may not be required or allowed in all scenarios, see each API for more detail.

API Key

Your API key is required in most REST calls to your instance (except session management and some system calls), and is used as part of the system authentication process. It is generated for you when you create each application and can be regenerated if compromised.

URL Parameter - api_key=<your_api_key_here>
HTTP Header - X-DreamFactory-API-Key: <your_api_key_here>

Session Token

For all authenticated requests made (outside of the browser session control) after logging in to the API, you’ll need to pass the session_token received in the login response along with each call to authenticate the request. This can currently only be done in the following way:

URL Parameter - session_token=<your_session_token_here>
HTTP Header - X-DreamFactory-Session-Token: <your_session_token_here>

Request Format

For request data formats, where applicable, the default is JSON. This can be overwritten by using the following options:

URL Parameter - content_type=<format_option>
HTTP Header - Content-Type: <format_option>

Response Format

You can specify what format or content type you would like to receive back by using the Accept header, with a value of either "application/json" (which is the default for the API) or others like "application/xml", where _format_option_ can be "application/json" (default for the API), "application/xml", etc.

URL Parameter - accept=<format_option>
HTTP Header - Accept: <format_option>

HTTP Verb Tunnelling

In some scenarios, like web-servers or routers not supporting the 'DELETE' HTTP verb, or complicated filter requests for databases that require posting data instead or URL parameters, tunneling the actual request verb inside a POST may be required. To accomplish this, use the following options on POST requests, where _verb_ can be "GET", "PUT", "PATCH", or "DELETE".

URL Parameter - method=<verb>
HTTP Header - X-HTTP-METHOD: <verb>

Content-Encoding

If your client/browser supports (which all modern browsers do) compressed content, then you can set up your web server to return response in a compressed format such as gzip, deflate, etc. When contents are delivered by the server in a compressed format, it takes a lot less bandwidth than it would normally take to deliver the uncompressed content. Compression speeds up the overall content delivery and response time.

If your client is capable of accepting compressed content, then it specifies the compression format (gzip, deflate etc.) in the request header Accept-Encoding. On the other side, if your server is configured properly and supports the compression format specified in the request header, it then compresses the response and delivers it to the client. The server uses Content-Encoding response header to indicate which format is used for the compressed content.

You can easily configure the two main web servers - Nginx and Apache to enable compressed response content.

Nginx

Put the following directives in your VirtualHost config section. To know more about these directives click here. To know more about Nginx response compression/decompression click here.

   gzip on;
   gzip_disable "msie6";

   gzip_vary on;
   gzip_proxied any;
   gzip_comp_level 6;
   gzip_buffers 16 8k;
   gzip_http_version 1.1;
   gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;

Sample Nginx VirtualHost config for DreamFactory:

   server {
       listen 80 default_server;
       listen [::]:80 default_server ipv6only=on;
   
       root /path/to/dreamfactory/public;
       index index.php index.html index.htm;
   
       server_name server_domain_name_or_IP;
       
       gzip on;
       gzip_disable "msie6";
   
       gzip_vary on;
       gzip_proxied any;
       gzip_comp_level 6;
       gzip_buffers 16 8k;
       gzip_http_version 1.1;
       gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript; 
       
       location / {
           try_files $uri $uri/ /index.php?$args;
       }
   
       error_page 404 /404.html;
       error_page 500 502 503 504 /50x.html;
       location = /50x.html {
           root /usr/share/nginx/html;
       }
   
       location ~ \.php$ {
           try_files $uri =404;
           fastcgi_split_path_info ^(.+\.php)(/.+)$;
           fastcgi_pass unix:/var/run/php5-fpm.sock;
           fastcgi_index index.php;
           fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
           include fastcgi_params;
       }
   }

Apache

Apache requires mod_deflate to be installed and enabled for this. After that just need to specify AddOutputFilterByType DEFLATE config inside the Directory settings for your VirtualHost config. To find out more about mod_deflate click here.

Sample Apache VirtualHost config for DreamFactory:

   <VirtualHost *:80>
       DocumentRoot /opt/dreamfactory/public
   
       <Directory /opt/dreamfactory/public>
           AddOutputFilterByType DEFLATE text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript
           Options -Indexes +FollowSymLinks -MultiViews
           AllowOverride All
           AllowOverride None
           Require all granted
           RewriteEngine on
           RewriteBase /
           RewriteCond %{REQUEST_FILENAME} !-f
           RewriteCond %{REQUEST_FILENAME} !-d
           RewriteRule ^.*$ /index.php [L]
   
           <LimitExcept GET HEAD PUT DELETE PATCH POST>
               Allow from all
           </LimitExcept>
       </Directory>
   </VirtualHost>

NOTE: It is also possible to send a compressed request body to the server and let the server side decompress it before passing it to the application. However, this is not that widely used and browsers typically do not compress the request body automatically. You can always compress your request body in your client application and use Content-Encoding header to indicate the compression format used. On the server side, Nginx does not support decompressing a request body out of the box. Apache can take care of this by using the mod_deflate module. You can find more about this here.

Common Service Types

The DreamFactory REST API consist of dynamic service types, so the possibilities of the API are limitless. However, several come standard with every instance or are common additions. They are listed here with links to our Live API to try them out.