Using the API Docs

From DreamFactory
Jump to: navigation, search
DreamFactoryTutorialsUsing the API Docs

DreamFactory's API Docs allow you to make REST API calls to the services on your instance. This tutorial will show you how to access the the default 'db' service. The process is similar for other database types. To access the API Docs click the 'API Docs' tab in the DreamFactory admin console.

<screenshot>

Get a List of Resources

Find your SQL service in the list and click the first ‘GET’ to expand. Click the ‘Try it out!’ button and you should see the request URL and response. The response body will show the available resources for this service.

<screenshot>

Get a List of Tables

To get a list of tables on this service, click on ‘GET /db/_schema’. This adds ‘/_schema’ to the previous URL and returns a list of tables for the database.

<screenshot>

Create a New Table

If the result shows an empty resource array then your database has no tables. Go to ‘POST /db/_schema’ and click the green button to expand. Enter the following schema in the ‘tables’ text area then click ‘Try it out!’. After creating a new table you should flush the system cache from the Config—>Cache tab in the admin console.

POST https://your-url/api/v2/db/_schema
{
  "resource": [
    {
      "name": "todo",
      "label": "Todo",
      "plural": "Todos",
      "alias": null,
      "field": [
        {
          "name": "id",
          "label": "Id",
          "type": "id"
        },
        {
          "name": "name",
          "label": "Name",
          "type": "string",
          "size": 80,
          "allow_null": false
        },
        {
          "name": "complete",
          "label": "Complete",
          "type": "boolean"
        }
      ]
    }
  ]
}


Now go back to ‘Get a List of Tables’ and you’ll see the new table in the list.

<screenshot>

Get Records from a Table

To retrieve records for a particular table like ‘todo’, click on ‘GET /db/_table/{table_name}’ and set {table_name} to ‘todo’ in the drop-down menu.

<screeenshot>

Click “Try it out!’ to get the records. This returns all records in that table, up to the max configured value. You can use query parameters such as filter, limit, and offset to control what records are returned, including relational queries.

<screenshot>

Create Records for a Table

If the result shows an empty resource array then you have no records in that table. Go to ‘POST /db/_table/{table_name}’ and click the green button to expand. Enter the following in the ‘body’ text area then click ‘Try it out!’.

POST https://your-url/api/v2/db/_table/todo
{
  "resource": [
    {
      "name": "test1"
    },
    {
      "name": "test2"
    }
  ]
}


This will create two new records in the ‘todo’ table. The default for creating records is to return the ids but you can use the ‘fields’ query param to specify which fields are returned. Now go back to ‘GET /db/_table/{table_name} and set the table_name to ‘todo’. You should get back the records you just created.

Updates and deletes are handled in a similar manner similar. You can update and delete by id or by filter. For SQL services, PUT and PATCH are essentially the same thing. From the API Docs you can also call stored procedures and functions if your database supports them.