API

From DreamFactory
Jump to: navigation, search

The DreamFactory REST API is a REST-ful implementation of our 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 accesses assigned to the user, or based on default role access assigned to each application for non-authenticated calls.

A very cool tool to help you with our REST API is the Live API application, also know as "swagger", included with every instance. An example of our Live API can be viewed here.

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 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 [Auth Overview](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. We have also added support for PATCH. In certain services, HEAD and OPTIONS verbs may be supported as well. We also support 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.

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 setup 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, therefore, 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 then delivers 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 configs click [here.](http://nginx.org/en/docs/http/ngx_http_gzip_module.html#gzip_comp_level) To know more about Nginx response compression/decompression click [here.](https://www.nginx.com/resources/admin-guide/compression-and-decompression/) 

   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.](http://httpd.apache.org/docs/current/mod/mod_deflate.html)

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 then on 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 do not support decompressing 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.](http://httpd.apache.org/docs/current/mod/mod_deflate.html)

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.

cURL Examples

// login as an admin - POST to /system/admin/session

  • Use returned session_token as X-DreamFactory-Session-Token header in subsequent calls
curl -i -k -3 -X POST "http://localhost:8080/api/v2/system/admin/session" \
 -d '{ "email" : "[email protected]", "password" : "pass123" }' \
 -H "Content-Type: application/json"

// login as a user - POST to /user/session

  • Use returned session_token as X-DreamFactory-Session-Token header in subsequent calls
curl -i -k -3 -X POST "http://localhost:8080/api/v2/user/session" \
 -d '{ "email" : "[email protected]", "password" : "pass123" }' \
 -H "Content-Type: application/json"

// get all records from table named todo 

curl -i -k -3 -X GET "http://localhost:8080/api/v2/db/_table/todo" \
  -H "X-DreamFactory-Api-Key: <api key for app in the apps tab>" \
  -H "X-DreamFactory-Session-Token: <session token from login response>"

// create new todo 

curl -i -k -3 -X POST "http://localhost:8080/api/v2/db/_table/todo" \
  -H "X-DreamFactory-Api-Key: <api key for app in the apps tab>" \
  -H "X-DreamFactory-Session-Token: <session token from login response>" \
  -H "Content-Type: application/json" \
  -d '{"resource":[{ "name" : "curl todo", "complete" : false }]}'

// update todo with id = 1 

curl -i -k -3 -X PATCH "http://localhost:8080/api/v2/db/_table/todo/1" \
  -H "X-DreamFactory-Api-Key: <api key for app in the apps tab>" \
  -H "X-DreamFactory-Session-Token: <session token from login response>" \
  -H "Content-Type: application/json" \
  -d '{ "complete" : true }'

// delete todo with id = 1 

curl -i -k -3 -X DELETE "http://localhost:8080/api/v2/db/_table/todo/1" \
  -H "X-DreamFactory-Api-Key: <api key for app in the apps tab>" \
  -H "X-DreamFactory-Session-Token: <session token from login response>"

// logout as an admin - DELETE /system/admin/session 

curl -i -k -3 -X DELETE "http://localhost:8080/api/v2/system/admin/session" \
  -H "X-DreamFactory-Session-Token: <session token from login response>"

// logout as a user - DELETE /user/session 

curl -i -k -3 -X DELETE "http://localhost:8080/api/v2/user/session" \
  -H "X-DreamFactory-Session-Token: <session token from login response>"
Retrieved from "https://wiki.dreamfactory.com/index.php?title=DreamFactory/API&oldid=32294"