Upgrading Your App

The REST API has changed a bit since version 1.x. If you've created an application that uses version 1.x, and you want to update it to use version 2.0 or later, here are the steps we recommend. If you have any difficulties you can contact [email protected] or visit the forums for help.

Export your app as a package file

From your 1.x instance, export your application, along with any required schema from the 'db' service, to a DreamFactory package file. Go to the Packages tab in the admin console and select your application. Check the checkbox for exporting source code if applicable. Click the Export button, and a file will be downloaded to your local machine. This is just a zip file, so you can change the extension to .zip to examine the contents.

Create a new app on your 2.0 instance

On your 2.0 instance go to the Apps tab in the admin console. Click Create, then complete the form. Be sure to select the proper type for your app. Click Create Application, then click Manage and you'll see your new app in the list. Notice it has an API key. This key is sent as a header named 'X-DreamFactory-Api-Key' and replaces the 'X-DreamFactory-Application-Name' header from 1.x. In 2.0 the app name is only for display purposes and is not included in API calls.

Add services to your 2.0 instance

Any services you added to your 1.x instance will need to be added to your 2.0 instance. Go to the Services tab in the admin console and click Create. Select the service type, and complete the forms. In 2.0 the 'db' service is SQLite and comes preconfigured with every DreamFactory instance. Bitnami installs also include MySQL and MongoDB by default. If you only used the 'db' MySQL service in 1.x, then you can most likely use the 'db' SQLite service in 2.0, unless you were using features not supported by SQLite.

Import 1.x schema into 2.0 instance

This step is optional, and only suggested if you were using the 'db' MySQL service in 1.x and want to move that schema to the 'db' SQLite service in 2.0. If your schema is not too complex, it's easier to use the schema manager to recreate the table in your 2.0 instance. See next section for details. If you want to modify and import the exported 1.x schema here's how. Unzip the package file you exported from your 1.x instance. This will include a file named 'schema.json' that contains any exported schema. There's some manual conversion to be done. This example is for a table named todo with three fields. Remove the 'service' array wrapper and service 'api_name'. The service will be selected in the admin console schema manager before you click on 'Upload JSON'. Replace 'table' with 'resource'. Paste schema into the editor and click the Upload button.

OLD Exported Schema

{
"service": [{
"api_name": "db",
"table": [{
"name": "todo",
"label": "Todo",
"plural": "Todos",
"primary_key": "id",
"name_field": "",
"field": [{
"name": "id",
"label": "Id",
"type": "id",
"db_type": "int(11)",
"length": 11,
"precision": 11,
"scale": 0,
"default": null,
"required": false,
"allow_null": false,
"fixed_length": false,
"supports_multibyte": false,
"auto_increment": true,
"is_primary_key": true,
"is_foreign_key": false,
"ref_table": "",
"ref_fields": "",
"validation": null,
"value": []
}, {
"name": "name",
"label": "Name",
"type": "string",
"db_type": "varchar(80)",
"length": 80,
"precision": 80,
"scale": 0,
"default": null,
"required": true,
"allow_null": false,
"fixed_length": false,
"supports_multibyte": true,
"auto_increment": false,
"is_primary_key": false,
"is_foreign_key": false,
"ref_table": "",
"ref_fields": "",
"validation": null,
"value": []
}, {
"name": "complete",
"label": "Complete",
"type": "boolean",
"db_type": "tinyint(1)",
"length": 1,
"precision": 1,
"scale": 0,
"default": null,
"required": false,
"allow_null": true,
"fixed_length": false,
"supports_multibyte": false,
"auto_increment": false,
"is_primary_key": false,
"is_foreign_key": false,
"ref_table": "",
"ref_fields": "",
"validation": null,
"value": []
}],
"related": [],
"access": ["GET", "POST", "PUT", "PATCH", "MERGE", "DELETE"]
}]
}]
}

NEW Schema to Import

{
"resource": [{
"name": "todo",
"label": "Todo",
"plural": "Todos",
"primary_key": "id",
"name_field": "",
"field": [{
"name": "id",
"label": "Id",
"type": "id",
"db_type": "int(11)",
"length": 11,
"precision": 11,
"scale": 0,
"default": null,
"required": false,
"allow_null": false,
"fixed_length": false,
"supports_multibyte": false,
"auto_increment": true,
"is_primary_key": true,
"is_foreign_key": false,
"ref_table": "",
"ref_fields": "",
"validation": null,
"value": []
}, {
"name": "name",
"label": "Name",
"type": "string",
"db_type": "varchar(80)",
"length": 80,
"precision": 80,
"scale": 0,
"default": null,
"required": true,
"allow_null": false,
"fixed_length": false,
"supports_multibyte": true,
"auto_increment": false,
"is_primary_key": false,
"is_foreign_key": false,
"ref_table": "",
"ref_fields": "",
"validation": null,
"value": []
}, {
"name": "complete",
"label": "Complete",
"type": "boolean",
"db_type": "tinyint(1)",
"length": 1,
"precision": 1,
"scale": 0,
"default": null,
"required": false,
"allow_null": true,
"fixed_length": false,
"supports_multibyte": false,
"auto_increment": false,
"is_primary_key": false,
"is_foreign_key": false,
"ref_table": "",
"ref_fields": "",
"validation": null,
"value": []
}],
"related": [],
"access": ["GET", "POST", "PUT", "PATCH", "MERGE", "DELETE"]
}]
}

Recreate tables using schema manageer

When you select 'Upload JSON' it shows you an example table which you can modify to suit your needs. In many cases this will be easier than trying to import schema from the 1.x package file. After editing the JSON, click Upload to save your new table. You can also use the UI to modify the table at any time.

Update your app code

The syntax of the API underwent some changes. Here are the basic steps to update your app code from 1.x to 2.0. We have a bunch of sample apps in GitHub. Go to dreamfactorysoftware and search for repos with 'sdk' in the name. They show authentication and CRUD for DreamFactory 2.0 using different platforms and frameworks.

• /rest changes to /api/v2
• /system/admin/session for admin login
• /user/session for user login
• /db/todo changes to /db/_table/todo
• record arrays wrapped with 'resource' not 'record', array is required
• App sends X-DreamFactory-Api-Key instead of X-DreamFactory-Application-Name
• App should send session token instead of session id
• Relationships are singular, related=contacts_by_account_id becomes related=contact_by_account_id

You can use the file manager to import your modified code into the storage service for your app (if any), or enable CORS and load everything from your local machine. Using CORS is the preferred way during development.