Update an App

When we talk about updating an app, we are almost always talking about creating a new version of an app. There is an exception, a new app version is NOT created if the app version being edited has a status of “inDevelopment” (draft) or “pending” – in which case, the current version of the app will be updated. This of course, all happens automatically behind the scenes within the OpenChannel API which means that app versioning is one less thing that you need to worry about. An app version is created by overwriting the required app fields for an existing app version as well as adding custom JSON (including URLs, texts, lists and other elements) to the customData field. An app version has a few distinct features:

  1. An app version can be created by a developer but cannot be viewed by a marketplace administrator until the app is published.
  2. Once approved by marketplace administrators, an app version cannot be modified by the developer. Any updates will create another app version that must be approved before the public details of the app can be updated.
  3. An app version (representing a new app or update to an existing app) can be rejected by marketplace administrators.

Loading and Collecting App Details

The first step to updating an app is to load the details of the app version into a form which can be done using the Get App Version API method.

The second step to editing an app is to collect details about the app from the developer to replace the details of the previous app version using the form. Notice that in this example below, the developerId is being set to an arbitrary value. In your implementation, you’ll want to set this value to the unique user identifier of the user that is submitting this app.

The API revolves around actions performed on behalf of users and developers. By utilizing this perspective it allows us to offer an API that is quick and simple to integrate. A userId always refers to the unique id that identifies the end users consuming the apps. A developerId always refers to the unique id that identifies the authors creating the apps.You don’t need to explicitly create users or developers on the OpenChannel platform. When you provide a new userId as part of an action, a user record is created automatically if a user with that id doesn’t already exist – the same goes for developers.

For security reasons, never reuse or hash userIds or developerIds. Providing unique ids to the Marketplace API is important for the proper operation of your marketplace.

Lets take a look at how we can structure form data to match the parameter requirements of the API:

Uploading Files and Images

Files and images can be uploaded to OpenChannel using the File Upload API method. Once a file is uploaded, the fileUrl in the API response can be added to your app by providing it within your customData JSON object structure.

For more details about uploading files and images see: Uploading Files for an App.

Updating the App

Once the new details of the app are collected, you can save the updated app version using the Update App API method. Once the update is complete, the result can be queried using the List App Versions API method. The status of an app dictates whether the app can be viewed on the marketplace or by marketplace administrators.

An example of how to update an app with id “5565322ae4b0a70b13a4563b”:

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/apps/5565322ae4b0a70b13a4563b/versions/1 
  -X POST 
  -H "Content-Type: application/json" 
  -d "{" 
        "'name':'Hot Water Assist'," 
          "'summary': 'Automatically set on/off timers...'," 
          "'description': 'HPWHs use electricity to move heat...'," 
          "'video': 'https://www.youtube.com/watch?v=i73n-LTXPIM'," 
          "'icon': 'https://s3.amazonaws.com/cloudexchange-uat/55653202e4b0a70b13a4562d.jpg'," 
            "'Hot Water'," 
            "'Smart Pump'" 
          "'author': 'Andrea'" 


Publishing the App

When an app version with the status “inDevelopment” is ready to be made publicly available on the marketplace, an app version can be published using the Publish App Version API method. Once published, the app becomes visible to marketplace administrators and receives a status of “pending”. The app will not become publicly visible to marketplace users until approved by a marketplace administrator.

An example of how to publish an app version for an app with id “5565322ae4b0a70b13a4563b”:

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/apps/5565322ae4b0a70b13a4563b/publish 
  -X POST  
  -d version=1 
  -d developerId="123"