Advice and answers from the Device Magic Team

Forms API

The forms API allows you to manipulate the forms of your organization, either through XML or JSON.

The API requires you to authenticate each call with your API token. Please see our authentication topic if you need to know more.

Base URL

The forms API is RESTful, operating on this base URL (note the HTTPS):

https://www.devicemagic.com/organizations/[organization_id]/forms

where your [organization_id] is the same ID in the URL when you’re logged in and viewing your forms at www.devicemagic.com with your browser.

Getting All Forms

To get an overview of all the forms belonging to your organization, simply issue an HTTP GET request to the Base URL.

https://www.devicemagic.com/organizations/[organization_id]/forms.(xml|json)

This will return a list of all your forms. e.g.

Request

https://www.devicemagic.com/organizations/1/forms.xml

Response

<?xml version="1.0"?>
<forms>
  <form>
    <id>2</id>
    <name>Sample Form Two</name>
    <namespace>http://mobileforms.devicemagic.com/xforms/4859c760-d9eb-012d-2595-123139016cf2</namespace>
    <version>1.04</version>
    <description/>
    <group>Unpublished</group>
   </form>
   <form>
     <id>1</id>
     <name>Simple Form</name>
     <namespace>http://www.devicemagic.com/xforms/simple</namespace>
     <version>1.0</version>
     <description/>
     <group>Unpublished</group>
  </form>
</forms>

And in JSON

Request

https://www.devicemagic.com/organizations/1/forms.json

Response

{
  "forms"=>
     [ {"id"=>2,
        "namespace"=>"http://mobileforms.devicemagic.com/xforms/4859c760-d9eb-012d-2595-123139016cf2",
        "version"=>"1.04",
        "description"=>nil,
        "group"=>"Unpublished"},
       {"id"=>1,
        "namespace"=>
        "http://www.devicemagic.com/xforms/simple",
        "version"=>"1.0",
        "description"=>nil,
        "group"=>"Unpublished"}
     ]
}

Getting From Definition

To get a form's definition you have to issue an HTTP GET request to:

https://www.devicemagic.com/organizations/[organization_id]/forms/[form_id].(xml|json)

This will return either the JSON or the XML body.

You may also optionally provide a version parameter.

For example:

Request:

https://www.devicemagic.com/organizations/1/forms/1.xml?version=1.03

Response:

<?xml version="1.0"?>
<h:html xmlns:h="http://www.w3.org/1999/xhtml" xmlns:dm="http://www.devicemagic.com/XMLSchemaDataTypes" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:ev="http://www.w3.org/2001/xml-events" xmlns="http://www.w3.org/2002/xforms">
  <h:head>
    <h:title>Untitled Form</h:title>
    <model>
      <instance xmlns="http://www.devicemagic.com/xforms/ns">
        <inputs>
          <Untitled_Question/>
        </inputs>
      </instance>
    </model>
  </h:head>
  <h:body>
    <input ref="Untitled_Question">
      <label>Untitled Question</label>
    </input>
  </h:body>
</h:html>

And in JSON

Request

https://www.devicemagic.com/organizations/1/forms/1.json

Response

{
  "type": "root",
  "children": [{
    "identifier": "Untitled_Question",
    "title": "Untitled Question",
    "autoIdentifier": true,
    "type": "text"
  }],
  "title": "Untitled Form"
}

Creating a New Form

To create a new form, you need to send an HTTP POST with the form definition to:

HTTP POST https://www.devicemagic.com/organizations/[organization_id]/forms

If you’re providing an XML definition for the form, set the content type in the request headers to application/xml:

Content-Type: application/xml

And as the POST body provide the XML definition:

<h:html
    xmlns='http://www.w3.org/2002/xforms'
    xmlns:dm='http://www.devicemagic.com/XMLSchemaDataTypes'
    xmlns:ev='http://www.w3.org/2001/xml-events'
    xmlns:h='http://www.w3.org/1999/xhtml'
    xmlns:xsd='http://www.w3.org/2001/XMLSchema'>
    <h:head>
        <h:title>Dummy Form</h:title>
        <model>
            <instance xmlns='http://www.devicemagic.com/xforms/dummy_form'>
                <untitled_form_1>
                    <alpha/>
                    <bravo/>
                </untitled_form_1>
            </instance>
        </model>
    </h:head>
    <h:body>
        <input ref='alpha'>
            <label>Alpha</label>
        </input>
        <input ref='bravo'>
            <label>Bravo</label>
        </input>
    </h:body>
</h:html>

On success you’ll receive a 201 Created, with a response body similar to this:

<form>
    <id>42</id>
    <namespace>http://www.devicemagic.com/xforms/dummy_form</namespace>
    <name>Dummy Form</name>
</form>

If the request fails, check the response header ‘Message’ for the reason. (Common issues include an invalid XML definition, or providing a namespace that is already in use.)

JSON forms work similarly. Send the POST to the same URL, with content type application/json:

HTTP POST https://www.devicemagic.com/organizations/[organization_id]/forms
Content-Type: application/json

A JSON form definition as the POST body:

{
    "type": "root",
    "children": [
    {
        "identifier": "Free_Text_Question",
        "title": "Free Text Question",
        "autoIdentifier": true,
        "type": "text"
    },
    {
        "identifier": "Sketch_Question",
        "title": "Sketch Question",
        "autoIdentifier": true,
        "type": "sketch"
    } ],
    "title": "Dummy Form",
    "description": "Testing sample"
}   

And the 201 Created on success will include a body like:

{
    "id": 129,
    "namespace": "http://www.devicemagic.com/xforms/dummy_sample",
    "name": "Test Form"
}

As with the XML, check the response header ‘Message’ for reasons if the creation fails.

Updating an Existing Form

To update an existing form, you need to send an HTTP PUT with the form definition to:

HTTP PUT https://www.devicemagic.com/organizations/[organization_id]/forms/[form_id]

If you’re providing an XML definition for the form, set the content type in the request headers to application/xml:

Content-Type: application/xml

And as the PUT body provide the updated XML definition:

<h:html
    xmlns='http://www.w3.org/2002/xforms'
    xmlns:dm='http://www.devicemagic.com/XMLSchemaDataTypes'
    xmlns:ev='http://www.w3.org/2001/xml-events'
    xmlns:h='http://www.w3.org/1999/xhtml'
    xmlns:xsd='http://www.w3.org/2001/XMLSchema'>
    <h:head>
        <h:title>Dummy Form</h:title>
        <model>
            <instance xmlns='http://www.devicemagic.com/xforms/dummy_form'>
                <untitled_form_1>
                    <alpha/>
                    <bravo/>
                </untitled_form_1>
            </instance>
        </model>
    </h:head>
    <h:body>
        <input ref='alpha'>
            <label>Alpha</label>
        </input>
        <input ref='bravo'>
            <label>Bravo</label>
        </input>
    </h:body>
</h:html>

You need to use the same form namespace in the updated definition as was in the original.

On success you’ll receive a 202 Accepted, with a response body similar to this:

<form>
    <id>42</id>
    <namespace>http://www.devicemagic.com/xforms/dummy_form</namespace>
    <name>Dummy Form</name>
    <version>1.1</version>
</form>

If the request fails, check the response header ‘Message’ for the reason.

JSON forms work similarly. Send the PUT to the same URL, with content type application/json:

HTTP PUT https://www.devicemagic.com/organizations/[organization_id]/forms/[form_id]
Content-Type: application/json

A JSON form definition as the PUT body:

{
    "type": "root",
    "children": [
    {
        "identifier": "Free_Text_Question",
        "title": "Free Text Question",
        "autoIdentifier": true,
        "type": "text"
    },
    {
        "identifier": "Sketch_Question",
        "title": "Sketch Question",
        "autoIdentifier": true,
        "type": "sketch"
    } ],
    "title": "Dummy Form",
    "description": "Testing sample"
}   

And the 202 Accepted on success will include a body like:

{
    "id": 129,
    "namespace": "http://www.devicemagic.com/xforms/dummy_sample",
    "name": "Test Form",
    "version": "1.1"
}

As with the XML, check the response header ‘Message’ for reasons if the update fails.

Deleting a Form

To delete a form, you need to send an HTTP DELETE to:

HTTP DELETE https://www.devicemagic.com/organizations/[organization_id]/forms/[form_id]

You’ll receive a 200 OK if the delete succeeded, and an HTTP error response otherwise.

Updating a Form’s Group

To change the group to which a form belongs (e.g. publish/un-publish), send an HTTP POST to:

HTTP POST https://www.devicemagic.com/organizations/[organization_id]/forms/[form_id]/properties

You can update either via JSON or XML.

If you use XML, set the content type in the request headers to application/xml:

Content-Type: application/xml

And provide an XML body, with the required group name (which is case sensitive), as below:

<form_properties>
    <group>Unpublished</group>
</form_properties>

If you prefer JSON, set the content type in the request headers to application/json:

Content-Type: application/json

And use a JSON body as below:

{
    "group": "Unpublished"
}

Please note that the group name is case sensitive, and must exist within your organization.

On success you’ll receive a 200 OK. If the request fails, check the response header ‘Message’ for the reason.

Did this answer your question?