What is an App?

An “app” can be a downloadable file, web application, embedded widget or anything you wish. You decide what defines an app or what information must be submitted for each app type. In fact, you can also have multiple app types within your app store simply by supplying a unique value in the app’s “appType” field.

Each app is a JSON representation of an application submitted by a developer. The structure of an app can be customized using the customData object. When creating or updating an app, the customData object can be set to hold fields and arrays which gives you the flexibility to completely customize the structure of your app. The OpenChannel platform will automatically detect and handle your custom app structure.

Creating an App

When we talk about creating an app, we are always talking about creating a new version of an app. An app version is created by populating the required app fields 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.

Collecting the App Details

The first step to create an app is to collect details about the app from the developer using a 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 author 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 OpenChannel 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.

Saving the App as a Draft

Once the details of the app are collected, you can save them as a new app version using the Create App API method. The new app version now has a status of “inDevelopment” and 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 create an app for a developer with id “123”:

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/apps 
  -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="30"