Application¶

You can create a new application in an organization through the Admin portal. The Admin portal creates the new application by issuing a post against the management endpoint (see the Creating an Application section in Organization for details). If you need to create an application programmatically in your app, you can also use the API to do this. You can access application entities using your app name or UUID, prefixed with the organization name or UUID:

https://api.usergrid.com/{org_name|uuid}/{app_name|uuid}

Most mobile apps never access the application entity directly. For example you might have a server-side web app that accesses the application entity for configuration purposes. If you want to access your application entity programmatically, you can use the API.

Creating an application¶

To create an application you POST a JSON object containing (at a minimum) the name of the new application. You will also need to pass authentication credentials.

Request URI¶

POST /management/organizations|orgs/{org_name}|{org_uuid}/apps {request body}

Parameters

Parameter	Sent in	Description
grant_type	Query string	Only the value ‘client_credentials’ is supported.
client_id	Query string	The org-level client id for your org, found in the ‘Org Administration’ menu of Usergrid portal.
client_secret	Query string	The org-level client secret for your org, found in the ‘Org Administration’ menu Usergrid portal.
name	Request Body	The name of the application.

Example - Request¶

curl -X -i POST "https://api.usergrid.com/management/orgs/testorg/apps?grant_type=client_credentials&client_id=b3U68vghI6FmEeKn9wLoGtzz0A&client_secret=b3U6ZuZ5_U8Y-bOaViJt0OyRkJFES-A" -d '{"name":"testapp1"}'

Example - Response¶

{
  "action": "new application for organization",
  "timestamp": 1338914698135,
  "duration": 701
}

Generating application credentials¶

Use the POST method to generate the client ID and client secret credentials for an application in an organization.

Request URI¶

POST /organizations|orgs/{org_name}|{uuid}/applications|apps/{app_name}|{uuid}/credentials

Parameters

Parameter	Description
string org_name\|arg uuid	Organization name or organization UUID.
string app_name\|arg uuid	Application name or application UUID.

Note: You also need to provide a valid access token with the API call. See Authenticating users and application clients for details.

Example - Request¶

curl -X POST "https://api.usergrid.com/management/orgs/testorg/apps/testapp1/credentials"

Example - Response¶

{
  "action": "generate application client credentials",
  "timestamp": 1349815979529,
  "duration": 535,
  "credentials":  {
    "client_id": "YXA7ygil-f3TEeG-yhIxPQK1cQ",
    "client_secret": "YXA65gYlqja8aYYSAy8Ox3Vg5aRZp48"
  }
}

Getting application credentials¶

Use the GET method to retrieve the client ID and client secret credentials for an application in an organization.

Request URI¶

GET /organizations|orgs/{org_name}|{uuid}/applications|apps/{app_name}|{uuid}/credentials

Parameters

Parameter	Description
string org_name\|arg uuid	Organization name or organization UUID.
string app_name\|arg uuid	Application name or application UUID.

Note: You also need to provide a valid access token with the API call. See Authenticating users and application clients for details.

Example - Request¶

curl -X GET "https://api.usergrid.com/management/orgs/testorg/apps/testapp1/credentials"

Example - Response¶

{
  "action": "get application client credentials",
  "timestamp": 1349816819545,
  "duration": 7,
  "credentials":  {
    "client_id": "YXA7ygil-f3TEeG-yhIxPQK1cQ",
    "client_secret": "YXA65gYlqja8aYYSAy8Ox3Vg5aRZp48"
  }
}

Deleting and restoring Applications¶

Usergrid allows you to clean-up your Organizations by deleting old Applications that you no longer need. With this feature, Applications are not really deleted but they are hidden from view and may be restored later. (At some point in the future, Usergrid may get the ability to completely obliterate an Application, but that ability does not exist at the time of this writing.)

Delete Application: Request URI¶

Only an authenticated Admin User can delete and restore Applications. To delete an application, you send an authenticated HTTP DELETE request to the /management end-point. The Request URI must specify the Organization and the Application, both by identifier (name or UUID). Here is the Request URI pattern:

/management/organizations|orgs/{org_name}|{uuid}/applications|apps/{app_name}

Parameters

This is intentionally redundant, but you must confirm that you really want to delete the Application by specifying its name or UUID, same as that which you used in the Request URI.

Parameter	Description
string confirm_application_id	Application identifier (either name or UUID)

Note: You also need to provide a valid access token with the API call. See Authenticating users and application clients for details.

Delete Application: Example - Request¶

This example deletes an aApplication named ‘testapp1’

curl -X DELETE "https://api.usergrid.com/management/orgs/testorg/apps/testapp1?confirm_application_id=testapp1"

Delete Application: Example - Response¶

The response echos back the action that was taken and the params, and an HTTP 200 OK status message confirms that the Application has been deleted.

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Content-Length: 276
Content-Type: application/json
Date: Mon, 06 Jun 2016 18:52:04 GMT
Server: Apache-Coyote/1.1
Set-Cookie: rememberMe=deleteMe; Path=/; Max-Age=0; Expires=Sun, 05-Jun-2016 18:52:04 GMT
{
    "action": "delete",
    "application": "d44dfc30-2c13-11e6-8b07-0a669fe1d66e",
    "applicationName": "delete",
    "duration": 3,
    "organization": "test-organization",
    "params": {
        "confirm_application_identifier": [
            "testapp1"
        ]
    },
    "timestamp": 1465239124645
}

Restore Application: Request URI¶

To Restore an Application that has been deleted you must know the Application’s UUID. If you do a PUT to that application’s old URI, using he UUID to identify it, then the Application will be restored.

Restore Application: Example - Request¶

For example, to restore ‘testapp1’ that we deleted above:

curl -X PUT "https://api.usergrid.com/management/orgs/test-organization/apps/d44dfc30-2c13-11e6-8b07-0a669fe1d66e access_token==YWMtZR..."

Restore Application: Example - Response¶

Here’s the response that indicates via HTTP 200 OK that the Application has been restored.

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Content-Length: 223
Content-Type: application/json
Date: Mon, 06 Jun 2016 19:03:16 GMT
Server: Apache-Coyote/1.1
Set-Cookie: rememberMe=deleteMe; Path=/; Max-Age=0; Expires=Sun, 05-Jun-2016 19:03:16 GMT

{
    "action": "restore",
    "application": "d44dfc30-2c13-11e6-8b07-0a669fe1d66e",
    "applicationName": "delete",
    "duration": 3,
    "organization": "test-organization",
    "params": {},
    "timestamp": 1465239796913
}

Application Delete and Restore Limitations¶

At the time of this writing there are a couple of limitations regarding Application Delete and Restore:

Within an Organization, you cannot delete an Application with the same name as an Application that you have deleted before.
Within an Organization, you cannot restore an Application is an application with the very same name has been added since the orginal one was deleted.

Hopefully, these unnecessary limitations will be fixed soon; they are tracked by this JIRA issue USERGRID-1299