App Creation

Create, edit, and manage apps and app versions on the Akana API Platform, and manage visibility.

API Platform Version: 8.1 and later

Table of Contents

  1. How do I add an app?
  2. How do I decide which security mechanism to use?
  3. How does an app consume APIs?
  4. How do I manage app visibility?
  5. How does app versioning work?
  6. How do I add an app version?
  7. How do I edit an app version?
  8. How do I delete an app version?
  9. How do I delete an app?
  10. How do I export an app?
  11. What are the contents of the app export file?
  12. How do I import an app from an export file?
  13. Related Topics

How do I add an app?

If you're logged in to the developer portal, in most cases you can add an app from the Plus Menu. See below.

In some cases, the Plus Menu might not include this option. If the option isn't available to you and you need to add an app, contact the Site Admin.

You might also want to add an app in the context of a specific business organization on the platform. See How do I manage apps for my organization?

To add an app
  1. From the Plus Menu, select Add a New App. The Add App page displays.
  2. Specify values for your app. The minimum values required are app name and description, version ID and version notes. Use the field descriptions below to help you make your choices:
    Name Description
    App Name A descriptive name for your app. When developing an app naming convention, note that your initial app name will be automatically assigned as the App Name for subsequent versions (for example, Version 1.0) and will be "App Name [App Version Name].
    Summary A brief, plain-text description of your app (optional). Text entered in this field is displayed in the list view.
    App Description A detailed description of your app. It's a good idea to include marketing, functional, and use case information.
    Version ID The app version name; for example, v1, Version 1.3.
    Version Notes A detailed description of your app version.
    Avatar You can optionally upload an avatar (icon) for your app. 75x75 pixels is the recommended size. For more information, see How do I upload and crop icons?
    Tags Tags or keywords that can be used to search for posts or tickets in the App or API Forums.
    Visibility Your app's visibility setting: Public, Private, or Registered Users.
    App ID (on some systems) A custom app identity for the current app definition. If left blank, the app will be randomly assigned an App ID (identity) in the format {fedmember} - {random-hex}. Note that an App ID cannot be changed after an App ID is assigned. You must create a new app version using the +Version function on the app's Details page and issue a custom app identity.
    Shared Secret (on some systems) A custom Shared Secret for the current app definition. If left blank, a shared secret is automatically generated and can be viewed using the Show Keys > Click to View function on the app's Details page. Depending on platform settings, the shared secret might be encrypted when displayed. A Shared Secret can be regenerated for a specific app using the Regenerate Key function on the app's Details page.
    App Website A URL for the website associated with the app.
  3. Click Save. The app information is saved and posted to the app's Details page.

Note: In some cases, if an extension is in place, additional fields might appear in the bottom section of the Add App page. If so, these additional fields collect information about your app. Fields might be required or optional and might be of various types such as text-based or numeric, multiple selection, or dates. If you have questions about any of these fields, check the in-page tooltip (question mark to the right of the field) for help.

Back to top

How do I decide which security mechanism to use?

The security mechanism you choose for the messages your app will send to one or more APIs determines the level of security applied to the message. In general, a stronger security mechanism might include more setup or more processing on the part of your app. Your choices will be determined by such factors as the nature of your app and the nature of the messages your app will exchange with the API. For example, an app that processes financial transactions might require greater security than one that returns movie information.

In addition, the requirements or limitations of the specific API or APIs you are using are a key factor.

The platform supports the following security mechanisms:

  • HMAC Signature with Shared Secret
  • Hash/Digest with Shared Secret
  • RSA Signature with PKI
  • OAuth 1.0a
  • OAuth 2.0

Although the platform supports all of the above, a specific API hosted on the platform might not support them all. Check the API documentation for specific information about the security mechanisms supported.

For more information about the first three options, refer to App Security Options and Setup. For more information about OAuth options, refer to App Security.

Back to top

How does an app consume APIs?

After you create an app, several tasks must be performed so the app can consume an API.

Task Description
Identify APIs First, you must identify APIs you would like to add to your app. This can be done by performing a search via the Search menu and browsing the APIs on the API > Details page of each API.
Provision App with Authentication Key Next, you must provision the app with an authentication mechanism. When you create your app, an App ID and Shared Secret are automatically assigned. If you prefer to use PKI over Shared Secret to sign your app, you can generate an X.509 Certificate file (CER), or a Certificate Signing Request (CSR) and import it. See How do app credentials work?
Add APIs and gain access to Sandbox implementation

After determining which API you want to access, the next step is to submit an API Access Request to license an API and gain access to the Sandbox or Live implementation.

This task is performed using the API Access Wizard accessible by clicking the Access link on the API > Details page of a selected API. Here you select the APIs which you would like to license. For APIs that require license agreement acceptance, you must review and agree to the terms of one or more license agreements before access will be granted. The Policies section allows you to select one or more SLA policies to be used for monitoring API performance and quota management.

Access to Sandbox or Live implementations is, in most cases, automatically approved. The Sandbox or Live endpoints are available and visible in the My Apps > App > APIs page.

Build App The next step is to build your app as per the API requirements in terms of the semantics and security requirements of the API. Refer to the API documentation in the API > Documentation section of your API for more information.
Configure the app's OAuth profile settings

If your app will be using OAuth, specify preferences and configure the branding settings for the Grant Authorization page that your users will see, on the App Details > OAuth Profile page.

Complete App Testing in Your Sandbox Set up simulated user accounts and data in your sandbox and test your app.
Request Live Approval When you are finished testing and ready to gain access to the API's Live implementation, request access using the API Access Wizard. Upon approval, you will be ready to make calls to the Live endpoints.
Update Application with Live Endpoint When the status of the Live Endpoint is "Activated" you must then update your app with the Live implementation URL.
Activate After the Live implementation endpoint is updated in your app, you can select Activate.

Back to top

How do I manage app visibility?

When you create an app using Create a New App, you can control whether visibility of the app is Public or Private via the "Visibility" option. You can change app visibility based on your requirements using the Edit function on the app's Details page.

  • A public app is visible to all individuals that use the site, is searchable, and displays in the All Apps search filter.
  • A private app is visible to the creator, in the My Apps search filter, and to individuals that are members of the app team.

Back to top

How does app versioning work?

You might need to have more than one version of your app. For example:

  • You might want to have one version for support and/or testing, and another version for your customers to use.
  • You might want to have variations of your app that use different APIs.
  • You might want to separate usage monitoring, discussions, and ticket management by app version.

To facilitate this, the My Apps section includes app versioning functionality that allows you to create a new instance (version) of an existing app. You can have multiple app versions.

Creating the first app version

When you create an app, your app definition becomes the first version.

Adding another app version

After creating your app and first version, you can create an additional version. on the app's Details page, click Add Version. Define values in the same way as you did for the original app.

Each app has a unique AppID, and each app version has a unique AppVersionID. These IDs are used in the URL for platform pages for your app, and also used in API calls. For more information, refer to the API documentation in the API > Documentation section.

Viewing App Versions

To choose a specific app version, select it on the Version menu: Details page, top right.

Team Management

In My Apps, Team Member assignments apply to ALL apps versions. A unique set of Team Members cannot be assigned to a specific app version.

App Management

App versions can be managed using a variety of different tools available on the app's Details page.

Back to top

How do I add an app version?

If you are on the team for a specific app, you can add a new version at any time.

To create a new app version
  1. Navigate to My Apps > App Details for the app you would like to create a version for.
  2. Select + Version. The Edit App Info page displays. The following information displays:

    Name Description
    App Name A read-only field that displays the descriptive name for your app.
    Summary A brief, plain-text description of your app version (optional). Text entered in this field is displayed in the list view.
    App Description A read-only field that displays the detailed description of your app.
    Version ID The app version name; for example, v1, Version 1.3.
    Version Notes A detailed description of your app version.
    Avatar You can optionally upload an avatar (icon) for your app. 75x75 pixels is the recommended size. For more information, see How do I upload and crop icons?
    Tags A text box that allows you to enter tags or keywords that can be used to search for posts or tickets in the App or API Forums.
    App ID (in some systems) A text box that allows you to enter a custom app identity for the current app definition. If left blank, the app will be randomly assigned an App ID (identity) in the format {fedmember}-{random-hex}. Note that an App ID cannot be changed after it is assigned. You must create a new app version using the +Version function on the app's Details page and issue a custom app identity.
    Shared Secret (in some systems) A text box that allows you to enter a custom Shared Secret for the current app definition. If left blank, a shared secret is automatically generated and can be viewed using the Show Keys > Click to View function on the app's Details page. Depending on platform settings, the shared secret might be encrypted when displayed. A Shared Secret can be regenerated for a specific app using the Regenerate Key function on the app's Details page.
    Visibility Your app's visibility setting: Public, Private, or Registered Users.
    App Website A URL for the website associated with the app.

  3. Specify the Version ID, Tags, App Runtime ID (auto-generated if not specified), Shared Secret (auto-generated if not specified), Visibility (Public/Private), Version Description, and App Website (optional). Click Confirm to commit your changes.

Note: In some cases, if an extension is in place, additional fields might appear in the bottom section of the Add App Version page. If so, these additional fields collect information about your app. Fields might be required or optional and might be of various types such as text-based or numeric, multiple selection, or dates. If you have questions about any of these fields, check the in-page tooltip (question mark to the right of the field) for help.

Back to top

How do I edit an app version?

You can change app version information using the Edit function in the app's Details page.

Note: In some cases, if an extension is in place, additional fields might appear in the bottom section of the app's Details page in a Properties section of the page. There is a separate Edit button to change these app properties. See To edit properties for an app version below. In many cases there won't be app properties.

To edit an app version
  1. Navigate to My Apps and click the link for your app. The app's Details page is displayed.
  2. At the top right, choose the app version.
  3. Click Edit. The Edit App Version page is displayed.
  4. Optional: on the left, modify any of these fields:
    • App name: A short and clear name to distinguish your app.
    • Summary: A short, plain-text field for internal display of the app description.
    • App Description: A concise description of the app that will attract users. Supports Markdown.
    • Version ID: A short and clear name to distinguish the version; for example, v1.
    • Version Notes: Supplementary information to describe the app version.
  5. Optional: on the right:
    • Upload an avatar for the app version.
    • Change the parent organization by providing the new value in the Parent Organization Name field. Start typing the new organization name in the field. After the first three characters, the platform displays a list of matching organizations for you to choose from. For more information about organizations on the platform, see Organizations.
    • Modify the Visibility value for the app.
    • Enter a user-defined App ID.
    • Add or update the shared secret key.
    • Add or update the fully-qualified URL for your app's website.
  6. Click Finish.
To edit properties for an app version:

Note: Depending on platform configuration, additional properties for apps might vary or might not appear at all.

  1. Navigate to My Apps > App. The app's Details page is displayed.
  2. Select the app version at the top right.
  3. In the Properties section, click Edit.
  4. Edit the properties as needed. For help, refer to field-level help if needed. If you need additional assistance, contact the Site Admin.
  5. Click Finish.

Back to top

How do I delete an app version?

You can delete an app version on the app's Details page.

Note: If you want to delete an old version and add a new version, add the new version first. If you delete the only version, the app is deleted. If you add the new version, you can then delete the older version.

To delete an app version
  1. Navigate to My Apps.
  2. From the Version menu at the top right of the page, choose the version you want to delete.
  3. Click Delete Version.
  4. At the confirmation message, click OK. The app version is deleted.

Back to top

How do I delete an app?

When there is only one version of an app, and you delete it, the entire app is deleted. If there is more than one version, and you want to delete the app, you must delete each version separately.

Note: In some cases, the platform might be set up so that deleting an app requires Business Admin approval. If this is the case, and you attempt to delete the app, you will see a message that the deletion request has been sent for approval. The app is inactivated pending approval; at this point, only the Business Admin can make changes. When the Business Admin approves the request, the app is fully deleted. If for any reason the Business Admin denies the request, the app is restored to normal operation.

To delete an app
  1. Follow the instructions in To delete an app version above.
  2. The confirmation message warns you that deleting the last version deletes the app. Click OK to confirm. The app is deleted.

Back to top

How do I export an app?

You can export information about an app to an external file. You can then import that file to another instance of the platform. One use of this feature is to move data from one environment to another, such as from a development environment to a testing environment.

You can choose to export information about a single app version or all app versions. You can also choose whether or not to export additional data associated with the app.

To export an app:
  1. Navigate to the app's Details page (My Apps > choose the app).
  2. Click Export.
  3. In the Export dialog, choose export versions (current version or all versions) and choose export options. If you want to export all information about the app, check all boxes. You can choose to export the following additional data associated with the app:
    • Export App PKI
    • Export API Contracts
    • Export App Team Members
      Note: the relationship of the user as an app team member is exported, but the user is not exported. The user must exist in the target environment. If the user does not exist when the information is imported, the app is created without that team member. From there it can be fixed in several ways: a) the user can sign up and be invited to be an app team member, b) the user can sign up and the app data can be reimported, c) another individual can be designated as an app team member.
  4. Click Export.
  5. Choose to save or open the export file. By default, the export package file is named application-export.zip and is saved to your default downloads folder.

Back to top

What are the contents of the app export file?

The app export file includes all the core information about the app, as well as any of the optional additional information you specified.

The file has a very specific structure. It will generally include the following files at root level:

  • objectgraph.xml: An XML file that shows the relationships between resources.
  • objectdata.xml: An XML-based summary of all the data in the export file.
  • exportproperties.properties: a properties file showing which options were included in the export file.

If PKI information was chosen to be exported, it is stored in a separate pki subfolder.

Back to top

How do I import an app from an export file?

Any member of the app team, or a Business Admin, can export information about an app to an external file. However, only a Business Admin can import.

If you need help with import functions, contact your Business Admin.

If you are a Business Admin, refer to How do I import site, app, or API information from an export file? for instructions.

Back to top