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

    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 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.

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

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

    1. <a name="curl"></a>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" }'
    • // 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" }'
    • // 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>" \
  -d '{ "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>" \
  -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=31605"