Application version API

This allows the configuration of versions for mobile apps via a REST API. The Application version API offers the same functionality as the Admin interface and can be integrated in a Continuous Delivery (CD) environment.

• Endpoints
  • List of App versions per platform
  • Create App version
  • Clone App version
  • Update App version
  • Export App version config
• Error codes

Endpoints

All endpoints are protected via basic authentication, using the API client credentials. It requires an API client with the scope onegini_api_config (Config API).

List of App versions per platform

This returns a list of all App versions per platform and their status. An App version can have 3 statuses:

• DISABLED
• LOGIN_ONLY
• LOGIN_REGISTRATION.

When an App version is DISABLED, users must download a newer version of the app. With LOGIN_ONLY the registered users can still use this version, but new users cannot register. The status LOGIN_REGISTRATION lets new users register for this app and existing users can log in.

• Endpoint: /api/v1/configuration/applications/{appId}/platforms/{platform}/versions
• Method: GET

Path parameters:

Example request:

GET /api/v1/configuration/applications/myApp/platforms/ios/versions HTTP/1.1
Host: onegini.example.com
Content-Type: application/json

Example success response:

HTTP/1.1 200 Ok
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  [
    {
      "version_name": "1.1.0",
      "status": "LOGIN_ONLY"
    },
    {
      "version_name": "1.10.0",
      "status": "LOGIN_REGISTRATION"
    },
    {
      "version_name": "1.9.0",
      "status": "LOGIN_REGISTRATION"
    },
    {
      "version_name": "1.A",
      "status": "DISABLED"
    },
    {
      "version_name": "2.0.0",
      "status": "LOGIN_REGISTRATION"
    }
  ]
}

The version_name is a String and there is no fixed format. The status defines usage of this App version. Values are DISABLED, LOGIN_ONLY and LOGIN_REGISTRATION.

In the event of an error, one of the generic error codes will be returned.

Create App version

This creates an App version from scratch.

• Endpoint: /api/v1/configuration/applications/{appId}/platforms/{platform}/versions
• Method: POST

Path parameters:

JSON body parameters:

Example request:

POST /api/v1/configuration/applications/myApp/platforms/ios/versions HTTP/1.1
Host: onegini.example.com
Content-Type: application/json

{
  "version_name": "1.0.0",
  "app_signature": "secret",
  "tampering_protection": true,
  "payload_encryption": true,
  "status": "LOGIN_REGISTRATION",
  "push_messaging_configuration_id": "6727cf80-2807-11e6-b47f-89550f4d53bb",
  "use_apns_development_environment": false,
  "send_badge_number": true,
  "application_bundle_identifier": "com.example.myApp"
}

Example success response:

HTTP/1.1 201 CREATED
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

The success response body is empty.

In the event of an error, one of the generic error codes will be returned.

Clone App version

This creates a new App version with values from an existing App version. This can be useful when the new App version needs the same settings for payload encryption, tampering protection or push configuration.

• Endpoint: /api/v1/configuration/applications/{appId}/platforms/{platform}/versions/{originalVersionName}/clone
• Method: POST

Path parameters:

JSON body parameters:

Example request:

POST /api/v1/configuration/applications/myApp/platforms/ios/versions/3.0.0/clone HTTP/1.1
Host: onegini.example.com
Content-Type: application/json

{
  "version_name": "3.0.1",
  "app_signature": "secret",
  "status": "DISABLED"
}

Example success response:

HTTP/1.1 201 CREATED
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

The success response body is empty.

In the event of an error, one of the generic error codes will be returned.

Update App version

Some fields can be updated after creating an App version.

• Endpoint: /api/v1/configuration/applications/{appId}/platforms/{platform}/versions/{versionName}/
• Request method: PUT
• Please note that / at the end is required

Path parameters:

JSON body parameters:

Only the fields that are sent in the request will be changed.

Example request:

PUT /api/v1/configuration/applications/myApp/platforms/ios/versions/3.0.0 HTTP/1.1
Host: onegini.example.com
Content-Type: application/json

{
  "app_signature": "123456789012345678901234567890AB",
  "status": "LOGIN_REGISTRATION"
}

Example success response:

HTTP/1.1 204 NO CONTENT
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

The success response body is empty.

In the event of an error, one of the generic error codes will be returned.

Export App version config

This endpoint produces a ZIP file with the configuration that is needed by the Onegini SDK.

• Endpoint: /api/v1/configuration/applications/{appId}/platforms/{platform}/versions/{versionName}/export
• Method: GET

Path parameters:

Example Request:

GET /api/v1/configuration/applications/myApp/platforms/ios/versions/3.0.0/export HTTP/1.1
Host: onegini.example.com
application/zip;charset=UTF-8

Success response:

HTTP/1.1 200 
Content-Type: application/zip;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

The response body contains a ZIP file which is removed from the example for readability.

In the event of an error, one of the generic error codes will be returned.

Error codes

One of the following responses will be returned, containing a JSON object with an error code, a message and details about the error.