one app cloud - platform api
DESCRIPTION
With our new release you can store your form data and workflows in the back-end while extending the front-end with the platform API.TRANSCRIPT
ONE APP CLOUD – MARCH 2013 RELEASE
www.oneappcloud.com
March 2013 Release
With our new release we have made it easy to extend your form data and
visualize, enhance and combine it in a number of ways including :
1. Mobile Apps - Create a mobile application using One App Cloud as a back-end
database and workflow for your forms.
2. CRM Integration – Integrate with CRM systems like salesforce.com, SAP, Zoho
and more.
3. Push alerts – Register and send push notifications for your form submissions.
4. Application to application integration – Create custom web, desktop or mobile
apps using your form data.
One App Cloud
API API API
Mobile Google/Box and
others
Your Application
ONE APP CLOUD – MARCH 2013 RELEASE
www.oneappcloud.com
Getting Started
The One App Cloud API allows you to submit, edit, and retrieve data contained
within your One App account. In order to use the API, you will need your unique
API Key. Do not give out this key! The key works similar to your password, and
protects your data.
Introduction
The One App Cloud API is designed to unlock the potential of the data stored
inside your One App Cloud account. We provide all the tools required to build
applications, advanced reports and visualizations.
What’s even better is that you don’t need any programming experience to at least
view the data, because if you’re reading this, you already have the tools required:
a Web Browser. We’ve added a special parameter (pretty) to the request that
makes the process of exploring the API a simple, visual experience.
This documentation will demonstrate how to fetch data using APIs with the help
of sample URLs and screenshots of results.
API URL
/apiV1/{API-Name}
API-Name here will be the name of API call. If you want to fetch forms from your
account then API-Name will be “forms”.
Helping Parameters
ONE APP CLOUD – MARCH 2013 RELEASE
www.oneappcloud.com
We know that debugging scripts and code in a browser is a real pain. Keeping this
in mind, we’ve added a convenient GET parameter to provide a readable in
browser view of the output.
http://app.oneappcloud.com/one-app-cloud /apiV1/users?apiKey={API-Key-Here}
&respType=xml&pretty=true
The parameter “pretty” helps you fetching the response readable in browsers
with all the indentation and new lines. We escape < and > symbols if we find
“pretty” parameter to make sure it looks readable in the browser. Because most
browsers strip your tags away and show the content concatenated. This is a
convenient feature but only for debugging. While manipulating the response
don’t use this parameter. We also show the warning message for the same when
this parameter is used.
Are there any API restrictions?
We currently restrict you’re API usage to 200 requests per day.
How can to find API key?
Using Login API you can fetch your API key. API will be required in all the API calls
except for login.
Can users other than administrators use the API?
Each user is assigned an API key. Users who are not administrators will only be
able to access resources granted to them.
ONE APP CLOUD – MARCH 2013 RELEASE
www.oneappcloud.com
The Login API
The Login API is used to fetch the API key. You can see a call to this API in action
here:
Request URL:
https://app.oneappcloud.com/one-app-
cloud/apiV1/login?username={username}&password={password}[&pretty=true][
&respType={xml|json}]
The expected parameters of this request are:
{username} – This must be replaced with your username in your One App
Cloud account.
{password} – Your account’s password.
{respType} – Choose your response type values can be “xml” or “json”.
Default will be “json”.
{pretty=true} - The optional pretty=true get parameter formats your output
as HTML for debugging through the browser.
Sample Response
<Users> <User> <Id>1</Id> <FirstName>Adamn</FirstName>
ONE APP CLOUD – MARCH 2013 RELEASE
www.oneappcloud.com
<LastName>McLaren</LastName> <Username>[email protected]</Username> <ApiKey>3321-1877-46cf-9c08</ApiKey> <MobilePhone>+91 9888988898</MobilePhone> <OfficePhone></OfficePhone> <Role>ROLE_ADMIN</Role> <ImageURL>http://sphotos-a.xx.fbcdn.net/hphotos-ash3/c0.0.403.403/p403x403/578448_291595084287634_1086470129_n.jpg</ImageURL> </User> </Users>
Here you get your API key which will be required while using other APIs.
Users API
The Users API is used to gather details about the users you have created. You can
see a call to this API in action here:
Request URL:
https://app.oneappcloud.com/ one-app-cloud/apiV1/users?apiKey={API-Key-
Here}[&pretty=true][&respType={xml|json}]
The expected parameters of this request are:
{apiKey} – This must be replaced with your API key fetched from Login API.
ONE APP CLOUD – MARCH 2013 RELEASE
www.oneappcloud.com
Sample Response
<Users> <User> <Id>1</Id> <FirstName>Adamn</FirstName> <LastName>McLaren</LastName> <Username>[email protected]</Username> <ApiKey>3321-1877-46cf-9c08</ApiKey> <MobilePhone>+91 9888988898</MobilePhone> <OfficePhone></OfficePhone> <Role>ROLE_ADMIN</Role> <ImageURL>http://sphotos-a.xx.fbcdn.net/hphotos-ash3/c0.0.403.403/p403x403/578448_291595084287634_1086470129_n.jpg</ImageURL> </User> <User> <Id>2</Id> <FirstName>John</FirstName> <LastName>Kahn</LastName> <Username>[email protected]</Username> <ApiKey>a80b-818c-4024-8ec7</ApiKey> <MobilePhone></MobilePhone> <OfficePhone></OfficePhone> <Role>ROLE_HR_MANAGER</Role> <ImageURL>https://encrypted-tbn0.google.com/images?q=tbn:ANd9GcREYMDySIyzRZPZ1TmMfkBslZfSIoentMgfCAQ5f_7EYE35I1p_5Q</ImageURL> </User> </Users>
ONE APP CLOUD – MARCH 2013 RELEASE
www.oneappcloud.com
Forms API
The Forms API is used to gather details about the forms you have permission to
access. This API can be used to create a list of all forms belonging to a user and
dynamically generate a form embed snippet to use in your application. You can
see a call to this API in action here:
Request URL
https://app.oneappcloud.com/ one-app-cloud/apiV1/forms?apiKey={API-Key-
Here}[&formId={Form-Id}][&pretty=true][&respType={xml|json}]
The expected parameters of this request are:
{apiKey} – This must be replaced with your API key fetched from Login API.
{formId} – This option parameter is used to fetch the information related to
a specific form.
Sample Response
<Forms> <Form> <Id>1</Id>
ONE APP CLOUD – MARCH 2013 RELEASE
www.oneappcloud.com
<Name>Untitled Form</Name> <Description>Please fill out this form. Thank you!</Description> <Access>Public</Access> <RedirectMessage></RedirectMessage> <RedirectURL></RedirectURL> <StatusField></StatusField> <BlockUserChangeValues /> <ShowStatusToUser></ShowStatusToUser> <ResponseCount>6</ResponseCount> <RecentEntryTime>2013-02-13 17:00:28.0</RecentEntryTime> <RecentEntryId>2</RecentEntryId> <OpenForEdit>1</OpenForEdit> <FieldLabelAlignment>top</FieldLabelAlignment> <Font>Lucida Sans Unicode</Font> <FontSize>13</FontSize> <Heading>h2</Heading> <HeadingAlignment>left</HeadingAlignment> <HeadingFontWeight>bold</HeadingFontWeight> <HeadingFontStyle>normal</HeadingFontStyle> <HeadingTextDecoration>none</HeadingTextDecoration> <EmbededCSS></EmbededCSS> <EmbededJS></EmbededJS> <Recaptcha>0</Recaptcha> <DateCreated>2013-02-13 15:19:42.0</DateCreated> <LastUpdated>2013-02-15 18:44:33.0</LastUpdated> </Form> <Form> <Id>4</Id> <Name>Untitled Form</Name> <Description>Please fill out this form. Thank you!</Description> <Access>Public</Access> <RedirectMessage></RedirectMessage> <RedirectURL></RedirectURL> <StatusField></StatusField> <BlockUserChangeValues /> <ShowStatusToUser></ShowStatusToUser> <ResponseCount>0</ResponseCount>
ONE APP CLOUD – MARCH 2013 RELEASE
www.oneappcloud.com
<RecentEntryTime></RecentEntryTime> <RecentEntryId></RecentEntryId> <OpenForEdit>1</OpenForEdit> <FieldLabelAlignment>top</FieldLabelAlignment> <Font>Lucida Sans Unicode</Font> <FontSize>13</FontSize> <Heading>h2</Heading> <HeadingAlignment>left</HeadingAlignment> <HeadingFontWeight>bold</HeadingFontWeight> <HeadingFontStyle>normal</HeadingFontStyle> <HeadingTextDecoration>none</HeadingTextDecoration> <EmbededCSS></EmbededCSS> <EmbededJS></EmbededJS> <Recaptcha>0</Recaptcha> <DateCreated>2013-02-15 20:45:29.0</DateCreated> <LastUpdated>2013-02-15 20:45:29.0</LastUpdated> </Form> </Forms>
The <Form> Element
The <Form> element lives inside the parent “<Forms>. One <Form> element
exists for each form on your system. So, if you have 5 forms in your account and
you’re permitted to see them all, you’ll have 5 <Form> elements in the return
value from your API call.
Values for the <Form> element are defined below.
Name – The title of the form specified in the Form Settings in form
designer.
Description – The description of the form as specified in the Form Settings
in form designer.
Access – This parameter tell if the form is accessible by “logged in users” or
“public users” or “public users with a password”, specified in Form Settings.
Redirect Message – The confirmation message shown to users after they
have successfully filled out the form.
ONE APP CLOUD – MARCH 2013 RELEASE
www.oneappcloud.com
Redirect URL – Value of this tag is a URL where the user should be
redirected after the successful form submission. Its value is specified in
Form Settings.
StatusField – The parameter contains name of a field which is selected as a
status field in Form Settings.
BlockUserChangeValues – This parameter contains a value. If status field of
a form has this value then a user with role “ROLE_USER” should not be
allowed to update the entry.
ShowStatusToUser – This parameter tells if the status field should be
shown (Read-Only) to the user while editing an entry or not.
ResponseCount – Count of the number of entries for the form.
RecentEntryTime – Time of last entry made in the form.
RecentEntryId – ID for the most recent entry
OpenForEdit – The form’s entries are editable or not, specified in Form
Settings
FieldLabelAlignment – Alignment of the fields and their labels should be
top (one after another) or left (side by side) or right (side by side with labels
aligned in right near to the fields)
Font – Font-Family selected in Form Settings in Form Designer.
FontSize – Font-size selected in Form Settings in Form Designer.
Heading – Possible values: (h1, h2, h3, h4, h5, h6), tells how large/small the
size of heading should be, specified in Form Settings in Form Designer.
HeadingAlignment – Possible values: (left, right, center),
HeadingFontWeight – Font-weight of the Heading should be bold not.
HeadingFontStyle – Font-style of the Heading should be italic or not.
HeadingTextDecoration – Heading should be underlined or not.
EmbededCSS – This should be used if your application is a web application.
EmbededJS – This parameter also should be if your application is a web
application.
Recaptcha – Possible values: (0, 1), tells whether to add a captcha control
while user is to fill the form or not.
ONE APP CLOUD – MARCH 2013 RELEASE
www.oneappcloud.com
Fields API
The Fields API describes the hierarchy of your data. At the heart of this API is the
listing of Name values. Each Name corresponds to a value in the Entries API. Some
type of fields will not have Name, as those fields are not persistent, e.g. –
RichText, ImageUpload, Link and EmbedHTML.
Request URL
https://app.oneappcloud.com/ one-app-cloud/apiV1/fields?apiKey={API-Key-
Here}&formId={Form-Id}[&parentFormId={Parent-Form-
Id}][&pretty=true][&respType={xml|json}]
The expected parameters of this request are:
{apiKey} – This must be replaced with your API key fetched from Login API.
{formId} – This parameter is used to fetch the fields related to that form.
{parentFormId} – This optional parameter should be Parent Form’s id when
fields of a Sub-Form are to be fetched. To fetch Sub-Form’s fields this is
required.
ONE APP CLOUD – MARCH 2013 RELEASE
www.oneappcloud.com
The Standard Fields
Title – The Title is the friendly name you gave the field when creating your
form. For example, if you were building a table with the API, the Title would
be a column header.
Type – The Type represents a field type. A listing of these types can be
found in the Field Type section of this documentation.
Name – This is the unique reference for your field. There will be one
corresponding Name for each Entry in return value of the Entries API.
IsRequired – This value can be one or zero, representing whether or not the
field has been marked required in the Form Builder.
OtherOption – This value is one or zero and is only set if the field has
choices. Only CheckBox or Radio type fields have the option of
an Other field.
Sub-Fields
The more elaborate fields have Subfields. These include Date, Name, Checkbox,
Address, and Likert.
The example below shows a SubFields element from a Name field.
<SubFields>
<SubField>
<Name>field1360852056949pre</Name>
<Label>Prefix</Label>
</SubField>
<SubField>
<Name>field1360852056949fn</Name>
<Label>First Name</Label>
</SubField>
<SubField>
<Name>field1360852056949ln</Name>
<Label>Last Name</Label>
</SubField>
ONE APP CLOUD – MARCH 2013 RELEASE
www.oneappcloud.com
</SubFields>
The properties of subfields are defined here.
Name - This element works the same way a Name does for a Standard
Field. It, too, has a one-to-one relationship with the result of an Entries API
call.
Label - You need a friendly way to refer to the value of a Subfield. The Label
works similarly to the Title element. In most cases, however, this text is
determined by us. For example, the First Name and Last Name Text values
are predetermined.
Choices
Some fields, like the radio, dropdown and likert, represent a choice from several
available choices. These are represented in the <Choices> element, which in turn
has a series of <Choice> elements. The example below shows the choices for
a likert field.
<Choices>
<Choice>
<Score>1</Score>
<Label>Strongly Disagree</Text>
</Choice>
<Choice>
<Score>2</Score>
<Label>Disagree</Text>
</Choice>
<Choice>
<Score>3</Score>
<Label>Agree</Text>
</Choice>
<Choice>
<Score>4</Score>
ONE APP CLOUD – MARCH 2013 RELEASE
www.oneappcloud.com
<Label>Strongly Agree</Text>
</Choice>
</Choices>
A Choice element has the following elements:
Label - Is easy to picture if you think of a Drop Down. Each choice in the
DropDown is represented by a<Label> element.
Score - This is a text/number representing a choice’s value relative to the
other choices. For example, if there are four choices, the score ranges from
0 to 3 in case of likert type fields.
Putting it all together
The following is an example of the most complicated field type, the likert. Let’s
discuss what we’re seeing.
The Field Type is likert, which is like a combination of a checkbox and a select
type. The <Name> is field1357157506890. The subfields each have a Name as
well, because each represents a possible field value. So,
field1357157506890__0_, field1357157506890__1_, and
field1357157506890__2_ will all result in a corresponding entry value when the
Entries API is called. This is useful on the client side if you’re using standard like
XPath to navigate your DOM. The <Field> element also has a <Choices> element,
which represents the possible values for each of the <Subfield> elements.
<Field>
<Field>
<Name>field1357157506890</Name>
<DefaultValue></DefaultValue>
<IsRequired>0</IsRequired>
ONE APP CLOUD – MARCH 2013 RELEASE
www.oneappcloud.com
<IsHideFromUser>0</IsHideFromUser>
<Title>Likert 1</Title>
<Description></Description>
<Type>Likert</Type>
<Font>default</Font>
<FontSize>default</FontSize>
<FontWeight>bold</FontWeight>
<FontStyle>normal</FontStyle>
<TextDecoration>none</TextDecoration>
<SwitchRowCol>0</SwitchRowCol>
<SubFields>
<SubField>
<Name>field1357157506890__0_</Name>
<Label>Usability</Label>
</SubField>
<SubField>
<Name>field1357157506890__1_</Name>
<Label>Interface Look</Label>
</SubField>
<SubField>
<Name>field1357157506890__2_</Name>
<Label>Colors</Label>
</SubField>
</SubFields>
<Choices>
<Choice>
<Score>0</Score>
<Label>Very Satisfied</Label>
</Choice>
<Choice>
<Score>1</Score>
<Label>Satisfied</Label>
</Choice>
ONE APP CLOUD – MARCH 2013 RELEASE
www.oneappcloud.com
<Choice>
<Score>2</Score>
<Label>Neutral</Label>
</Choice>
<Choice>
<Score>3</Score>
<Label>Dissatisfied</Label>
</Choice>
</Choices>
<Page>1</Page>
</Field>
ONE APP CLOUD – MARCH 2013 RELEASE
www.oneappcloud.com
Entries API
The Entries API is used to gather the data that users have submitted to your form.
In this section we’ll describe the hierarchy of the entries element as well as
describe the syntax for filtering this data.
Request URL
https://app.oneappcloud.com/ one-app-cloud/apiV1/entries?apiKey={API-Key-
Here}&formId={Form-Id}[&parentFormId={Parent-Form-
Id}][&parentFormEntryId={Parent-Form-Entry-
Id}][&parentFormFieldName={Parent-Form-Field-Name-
Id}][&pretty=true][&respType={xml|json}]
ONE APP CLOUD – MARCH 2013 RELEASE
www.oneappcloud.com
The expected parameters of this request are:
{apiKey} – This must be replaced with your API key fetched from Login API.
{formId} – This parameter is used to fetch the entries related to that form.
{parentFormId} (Only required for Sub-Form’s entries) – This optional
parameter should be Parent Form’s id when entries of a Sub-Form are to be
fetched.
{parentFormEntryId} (Only required for Sub-Form’s entries) – This optional
parameter should be Parent Form’s Entry Id.
{parentFormFieldName} (Only required for Sub-Form’s entries) – This
optional parameter should be Parent Form’s Field’s Name in which the Sub-
Form is mapped.
The <Entry> Element
The <Entry> element lives inside the <Entries> parent. One <Entry> element exists
for each submission to your form. So, if you have 5 submissions to your form,
you’ll have 5 <Entry> elements in the return value from your API call.
Sample Response
Here’s an example of a call to the Entries API.
<Entries>
<Entry>
<Id>1</Id>
<field1357157498058>Sid</field1357157498058>
<field1357157498556>(610) 590-4444</field1357157498556>
<field1357157499090>2013-01-02 00:00:00.0</field1357157499090>
<field1357157499688>[email protected]</field1357157499688>
ONE APP CLOUD – MARCH 2013 RELEASE
www.oneappcloud.com
<field1357157500170>12.00</field1357157500170>
<field1357157501951>First Choice</field1357157501951>
<field1357157506890__0_>2</field1357157506890__0_>
<field1357157506890__1_>1</field1357157506890__1_>
<field1357157506890__2_>0</field1357157506890__2_>
<field1357157506890__3_>3</field1357157506890__3_>
<field1357157507791line1>123, ABC</field1357157507791line1>
<field1357157507791line2></field1357157507791line2>
<field1357157507791city>XYZ</field1357157507791city>
<field1357157507791state>PA</field1357157507791state>
<field1357157507791zip>28118</field1357157507791zip>
<field1357157507791country>US</field1357157507791country>
</Entry>
</Entries>
Paging
You can also request pages of data. This is useful because the maximum page size
for the Entries Api is 100. So if you wanted to page through your data 25 entries
at a time, you’d write paging arguments which looked like the example below.
pageStart=0&pageSize=25
Let’s look at the different parts of the example above.
pageStart - The page number you’d like to start from.
pageSize - The number of entries returned in your page.
Example
This concept is best explained with an example: So, if you’re filtering for all entries
whereField1 Contains Bob and the filter returned 1000 entries, and you
set pageStart=0 and pageSize=25you’d end up with the first 25 entries which fit
the filter. If you up the pageStart to 25 and left the pageSize the same, you’d get
the next 25 entries.
ONE APP CLOUD – MARCH 2013 RELEASE
www.oneappcloud.com
Some things to note about pageStart and pageSize:
pageStart defaults to 0
pageSize defaults to 25 and the maxim is 100
Entry Save API
To submit data to a form, you use the EntrySave API. This page will describe the
details of “POSTing” to your form.
Request URL
This API accepts POST requests in the following formats:
https://app.oneappcloud.com/ one-app-cloud/apiV1/entrySave
The expected parameters of this request are:
{apiKey} –API key fetched from Login API.
{formId} – Id of the form in which you want the entry response to be
added.
{parentFormId} (Only required for Sub-Form’s entries) – This optional
parameter should be Parent Form’s id when entries of a Sub-Form are to be
created.
{parentFormEntryId} (Only required for Sub-Form’s entries) – This optional
parameter should be Parent Form’s Entry Id.
{parentFormFieldName} (Only required for Sub-Form’s entries) – This
optional parameter should be Parent Form’s Field’s Name in which the Sub-
Form is mapped.
ONE APP CLOUD – MARCH 2013 RELEASE
www.oneappcloud.com
The <Entry> Element
After a successful POST to the EntrySave API, the system will send you
a <Entry> in the appropriate format as shown here:
<Entry>
<Saved>true</Saved>
<EntryId>8</EntryId>
</Entry>
Let’s review what these mean
Saved – This boolean value represents success or failure. So, the value true
means success, the value false means “no success”.
EntryId – The Entry ID created by this submission.
Dealing with failure
If the entry is not saved there could be some validation errors to show. The result
format in case of failure is shown below:
<Entry>
<Saved>false</Saved>
<EntryId></EntryId>
<Errors>
<Error>
<FieldName>field1362147308853</FieldName>
<ErrorMessage>Field Numeric Text 1 must be a valid number</ErrorMessage>
</Error>
</Errors>
</Entry>
Let’s see what these resulting elements mean
ONE APP CLOUD – MARCH 2013 RELEASE
www.oneappcloud.com
FieldErrors – The <Errors> element contains a collection
of <Error> elements.
FieldName – The unique identifier for the field. This corresponds to a Name
returned by the Fields API.
ErrorMessage – If contained within a <Error> element, this text describes
what went wrong when validating the field. Error Message contains
escaped HTML entities, so it may be displayed directly on a web page.