Why to Migrate from V3 to V4

The latest version of the CloudFactory API is V4. The new API offers intuitive naming and consistent data formatting making it easy to integrate the Platform with your application or maintain the integration. It also provides a slew of new capabilities allowing you to do more with the CloudFactory Platform. Moreover, V3 is already deprecated and is only in maintenance state. You'll miss out on all future enhancements if you stick to the deprecated version. For example, the new API already allows you to abort a production run and fetch results in a larger volume.

How to Migrate

You need to follow following steps to migrate from V3 to V4:

  1. Prepare your application to send input in the new format.

  2. Prepare your application to receive results in the new format.

  3. Work with your CloudFactory Production Manager to upgrade your production line.

Keep reading for the details.

#1 Modify the way you send work

First, change your application code to send input to a new endpoint.

The POST request should be sent to:

/v4/runs

Instead of: 

/v3/tasks

Second, the request body should be structured as:

{
   "line_id": "M4tCqxaL5tYou",
   "callback_url": "https://username:password@api.yourdomain.com/result",
   "units": [
      {
         "identifier": "0000001",
         "image_url": "http://yourdomain.com/assets/image_0000001.png",
         "company": "Microsoft"
      }
   ]
}

Instead of:

{
   "template_id":"M4tCqxaL5tYou",
   "callback_url":"https://username:password@api.yourdomain.com/v2/result",
   "resources":[
      {
         "identifier":"0000001",
         "image_url":"http://yourdomain.com/assets/image_0000001.png",
         "company":"Microsoft"
      }
   ]
}

Basically, following changes need to be made in the request body:

  1. Change the key template_id to line_id.
  2. change resources to units.

The immediate response from the Platform would be:

{
 "id": "E7gVrtVQJx",
 "line_id": "M4tCqxaL5tYou",
 "status": "Processing",
 "created_at": "2015-09-03T09:18:38Z"
}

Instead of:

{
 "task_id": "E7gVrtVQJx",
 "template_id": "M4tCqxaL5tYou",
 "status": "In-Progress",
 "started_at": "2015-09-17T07:36:05Z"
}

The change includes:

  1. task_id changes to just id. This is the id of the production run you just created.
  2. template_id changes to line_id. This is the id the production line in which you are creating a production run.

Basically, we are changing the key names to better reflect our standard terminology.

#2 Modify the way you receive result

When all the units in the production run are processed, you'll receive a response like this:

{
   "id": "E7gVrtVQJx",
   "line_id": "M4tCqxaL5tYou",
   "created_at": "2015-09-03T09:18:38Z",
   "processed_at": "2015-09-03T09:39:21Z",
   "status": "Processed",
   "units": [
      {
         "input": {
            "identifier": "0000001",
            "image_url": "http://yourdomain.com/assets/image_0000001.png"
         },
         "output":{
            "company": "Microsoft",
            "location": "USA"
         },
         "meta":{
            "status": "Completed",
            "created_at": "2015-09-03T09:18:38Z",
            "processed_at": "2015-09-03T09:25:28Z"
         }
      },
      {
         "input":{
            "identifier": "0000002",
            "image_url": "http://yourdomain.com/assets/image_0000002.png"
         },
         "output":{},
         "meta":{
            "status": "Flagged",
            "created_at": "2015-09-03T09:18:38Z",
            "processed_at": "2015-09-03T09:27:28Z"
         }
      }
   ]
}

The changes include:

  1. The task_id is renamed as id.
  2. The line_id is included in the response.
  3. The time fields (created_at and processed_at) are formatted in ISO 8601.
  4. The status is Processed instead of Completed.
  5. For each unit inside units (previously named resources), you'll find three distinct fields. The original inputs are in input, the output produced by the production line are in output, and other information about the unit are in meta. Refer to the documentation for further details about the data points exposed in meta.

#3 Upgrade the production line

Just talk to your CloudFactory Production Manager to have your production line upgraded. The change should take hours (some more complex lines may take longer). But before they make the change, you need to make sure that you have completed step #2 and step #3 in your application and time your release with the Production Manager’s release of your upgraded line. Otherwise the integration with your application might fail.

That's it. Check out the documentation to learn more about the new API.