API

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](https://df-wiki.enterprise.dreamfactory.com/swagger/).

1. 1. 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 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](Common-Headers-Parameters).
• **_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.

This **REST API** documentation consists of the following sections. Check out the [Common Headers and Parameters](Common-Headers-Parameters) section and the [Auth Overview](Authentication and Authorization) section before digging into the other sections.

1. 1. <a name="common"></a>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.

1. 1. 1. <a name="api-key"></a>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>`

1. 1. 1. <a name="session"></a>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>`

1. 1. 1. <a name="request-format"></a>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>`

1. 1. 1. <a name="response-format"></a>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>`

1. 1. 1. <a name="tunneling"></a>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>`

1. 1. <a name="services"></a>Common Service Types

• [System](https://df-wiki.enterprise.dreamfactory.com/swagger/index.html#!/system)
• [User](https://df-wiki.enterprise.dreamfactory.com/swagger/index.html#!/user)
• [SQL Database](https://df-wiki.enterprise.dreamfactory.com/swagger/index.html#!/db)
• [NoSQL Database](https://df-wiki.enterprise.dreamfactory.com/swagger/index.html#!/db)
• [File Storage](https://df-wiki.enterprise.dreamfactory.com/swagger/index.html#!/files)
• [Email](https://df-wiki.enterprise.dreamfactory.com/swagger/index.html#!/email)
• [API Docs](https://df-wiki.enterprise.dreamfactory.com/swagger/index.html#!/api_docs)

1. 1. Authentication