Articles in this section

API 5.1 to 6.0 Migration Guide

Avatar
Permanently deleted user
Updated
Follow

This guide is meant to help you make a transition from 5.1 to 6.0 in preparation of 5.1 and below removal.

PLEASE NOTE: API 5.1 and lower has been deprecated as of June 11, 2018 and we will no longer be making fixes or enhancements. You can read more about this here.

iFormBuilder API Migration Guide
What's covered:
Developer Migration Checklist:
Authentication

The same authentication method can be used in both 5.1 and 6.0.  Authentication is independent from the version endpoints.  To use API apps, take a look here and for creating JWT tokens, take a look here.

 

Noteworthy Changes

  • XML will no longer be an option for record data via API. Does not affect admin portal data feeds
  • Request BODY’s must be in JSON format, no longer in application/x-www-form-urlencoded.
  • Filtering enhancements
  • Number of objects returned in a call Records and Options response increased to 1000.
  • Added a COPY request for elements, forms, records, options and option lists.
  • Additional Resources - User and Form Groups,
  • Stronger Validation - Please follow api 6.0 doc for requirements and formats.
  • New response header that allows you to page through results.
  • API Behavior Differences
    • GET PAGE
      • 5.1 returns page and all elements.
      • 6.0 returns only page information. You must retrieve element info separately.
    • POST Optionlist
      • 5.1 can create a new list and options in one request.
      • 6.0 will only create the list, options must be added in a separate request.
    • DELETE Page
      • 5.1 records do not need to be deleted beforehand.
      • 6.0 all records must be deleted before delete page will work.
    • GET Records
      • 5.1 Subform records are sorted from old to new
      • 6.0 Subform records are sorted from new to old, except for when doing record feed.  Record feed documentation.

Updating Endpoints

5.1 endpoints are very similar to 6.0, with just one change. The example below is comparison between two specific element urls.  Keeping in mind that the body, headers, and response will be different.  There is ‘v60’ between ‘api’ and the start of defining a resource:

 

5.1 API

https://servername.iformbuilder.com/exzact/api/profiles/profile_id/pages/page_id/elements/element_id

 

6.0 API

https://servername.iformbuilder.com/exzact/api/v60/profiles/profile_id/pages/page_id/elements/element_id

 

Updating Code

In this section, this is where the biggest changes will happen.  These include what’s required in the headers and body, and what to responses to expect.

Headers

Request Headers

5.1

Required Headers

 

Authorization

Bearer {access_token}

X-IFORM-API-VERSION

5.1

X-IFORM-API-REQUEST-ENCODING*

JSON

*If sending body in JSON format

 

6.0

Required Headers

Authorization

Bearer {access_token}

Content-Type*

application/json

*If doing a PUT, POST or DELETE request that has a body.

Response Headers

5.1

 

allow

GET,POST,PUT

connection

Keep-Alive

content-encoding

gzip

content-length

331

content-security-policy

frame-ancestors ‘self’ https://zerionsoftware.com;

content-type

application/json

date

Thu, 11 Jan 2018 17:54:30 GMT

server

Apache

vary

Accept-Encoding

x-frames-options

SAMEORIGIN



6.0

 

Api-Request-Time

151693680

Connection

Keep-Alive

Content-Encoding

gzip

Content-Length

1574

Content-Security-Policy

frame-ancestors ‘self’ https://zerionsoftware.com;

Content-Type

application/json

Date

Thu, 11 Jan 2017 18:01:20 GMT

Memory-Max-Limit

134217728

Memory-Peak-Usage

34479552

Server

Apache

Time-Elapsed-Ms

206

Total-Count*

1313

Transaction-Id

0180f49e272892aff83c9d535c3e4b-e312d

Vary

Accept-Encoding

X-Frame-Options

SAMEORIGIN

 

*This is the total count that the response is pulling from.

 

Requests

Identical

GET and DELETE requests are handled the same, with the exception of being able to add filter parameters explained here to specify multiple objects in 6.0 (not available in 5.1).

Changes

  • GET and DELETE requests are handled the same.  The endpoint will specify which resource that will be retrieved or deleted.
  • POST and PUT only allows for JSON in 6.0.  x-www-form-urlencoded protocol will no longer be accepted as 5.1 did.
  • 6.0 allows for filtering and sorting of any resource.  This can be applied to GET, PUT and DELETE for some resources.  For example, DELETE all records that have a first name that starts with a ‘K’ in the records resource.  Look here for more information.
  • When creating records, an element’s data_column_name can be used as opposed from element id.

Sample Responses

5.1

6.0

GET Element

GET Element

Response:

{

  "ID":22350983,

  "PAGE_ID":408816,

  "NAME":"api_element_text_field",

  "VERSION":3,

  "CREATED_DATE":1368643810,

  "CREATED_BY":"calvina",

  "MODIFIED_DATE":1368644045,

  "MODIFIED_BY":"calvina",

  "DATA_TYPE":1,

  "DATA_SIZE":50,

  "LABEL":"API Text Field",

  "SORT_ORDER":1,

  "KEYBOARD_TYPE":"0",

  "STATUS":true

}

Response:

{
  "id": 20483236,
  "name": "inspector_name",
  "global_id": "0E20483236H5971E",
  "version": 3,
  "label": "Inspector Name",
  "description": "",
  "data_type": 1,
  "data_size": 50,
  "created_date": "2015-05-12T14:38:35+00:00",
  "created_by": "cng",
  "modified_date": "2015-05-12T14:49:41+00:00",
  "modified_by": "cng",
  "widget_type": "",
  "sort_order": 1,
  "optionlist_id": 0,
  "default_value": "",
  "low_value": 0,
  "high_value": 0,
  "dynamic_value": "iformbuilder.username",
  "is_required": false,
  "condition_value": "",
  "client_validation": "",
  "is_disabled": false,
  "reference_id_1": "",
  "reference_id_2": "",
  "reference_id_3": "",
  "reference_id_4": "",
  "reference_id_5": "",
  "attachment_link": "",
  "is_readonly": false,
  "validation_message": "",
  "is_action": false,
  "smart_tbl_search": "",
  "smart_tbl_search_col": "",
  "is_encrypt": false,
  "is_hide_typing": false,
  "on_change": "",
  "keyboard_type": 1,
  "dynamic_label": "",
  "weighted_score": 0,
  "localizations": []
}

Key Differences

  • 5.1 is Capitalized where as 6.0 is lower case
  • 5.1 Will only return objects that have values, whereas in 6.0 it returns all objects regardless if it has a value or not.  This applies to elements, forms, option and option lists.
  • STATUS object is no longer in 6.0

 

Sample POST

5.1

6.0

6.0

POST Record (JSON)

POST Record (element name)

POST Record (element id and name)

{

  "FIELDS":[

     {

        "ELEMENT_ID":22351042,

        "VALUE":"One"

     },

     {

        "ELEMENT_ID":22351031,

        "VALUE":"Jelly Beans"

     }

  ]

}

{
  "fields": [
    {
      "element_name": "how_many",
      "value": "One"
    },
    {
      "element_name": "inspector_name",
      "value": "Calvin Ng"
    }
  ]
}

{
  "fields": [
    {
      "element_id": 121069222,
      "value": "One"
    },
    {
      "element_name": "inspector_name",
      "value": "Calvin Ng"
    }
  ]
}

POST Response

POST Response

POST Response

{

  "RECORD_ID":3,

  "STATUS":true

}

{
  "id": 1
}

{
  "id": 1
}


This is a table that contains all the validations for 5.1 and 6.0 when creating a record.  Most of the validations are the same between the two, but there are some difference.

Element Type

5.1

6.0

Assign to

No Validation

Must be a user that has collect rights on form

Counter

No Validation (default 0 if string)

Must be number

Date

Must be YYYY-MM-DD

Must be YYYY-MM-DD

Date-Time

2018-16-02 10:30:57

Defaults 0 if proper format but bad number like 13 for month

2018-09-19T18:15:00+00:00

Drawing

Has to be BASE64 with encoding and extension

Can input URL or BASE64

E-Mail

Has to be proper email

Has to be proper email

ESRI

No Validation

No Validation

Image

Has to be BASE64 with encoding and extension

Can input URL or BASE64

Location

No Validation

No Validation

Multi-Select

Has to be valid key_value(s)

Has to be valid key_value(s)

Number

Must be a number

Must be a number

Phone

Must follow masking

Must follow masking

Pick List

Must be a valid single key value

Must be a valid single key value

Range

Has to be within the specified range

Has to be within the specified range

Read Only Widget

No Validation

No Validation

Select Widget

Must be a valid single key value

Must be a valid single key value

Signature

Has to be BASE64 with encoding and extension

Can input URL or BASE64

Sound

Has to be BASE64 with encoding and extension

Can input URL or BASE64

SSN

  

Must follow format masking

Text

No Validation

No Validation

Text Area

No Validation

No Validation

Time

Must follow HH:MM:SS

Must follow HH:MM:SS

Timer

SS:mm and M:SS.mm

SS:mm

Toggle

No validation, default 0

Has to be true, 0, 1.  False fails.

Zip Code

  

Must follow Zip code Validation



Related articles

Comments

2 comments

Sort by Date Votes
  • Avatar
    Gopi Ponnampalam (Edited )

    Hi there,

    I was only able to retrieve 100 record on a single call. Is there anyway to get all records ?

    0
    Comment actions Permalink
  • Avatar
    Tony Ruth

    Hi Gopi, the limits are intentional as APIs are designed to be lightweight and responsive. You can use a for loop and the offset parameter to get as many records as you need. 

    Hope that helps,

    Tony

    0
    Comment actions Permalink

Please sign in to leave a comment.

Powered by Zendesk