Applications

The EVRYTHNG Platform allows developers to create applications inside their projects. An application resource will usually correspond to an actual web or native applications (remote HTTP clients) that can interact with the EVRYTHNG API. The purpose of this resource is to grant API keys and manage users on behalf of the real-world app.

In this way all resources that are associated with the real-world counterpart app can be correctly scoped and grouped accordingly, for the purpose of the application as well as its users. Multiple applications can exist inside a project resource, with each granted its own Application and Trusted Application API Keys that can be used to manipulate only those resources in the application's project scope.

API Status
General Availability:
/applications/me
/projects/:projectId/applications
/projects/:projectId/applications/:applicationId
/projects/:projectId/applications/:applicationId/secretKey

Jump To ↓

ApplicationDocument Data Model
Create an application
Read applications in a project
Update an application
Delete an application
Read an Application
Read the Trusted Application API Key
Read Self Application
Update Self Application

ApplicationDocument Data Model

.name (string, required)
    Friendly name of this resource.

.socialNetworks (object, required)
    An array of social networks that this application will 
    support.

.id (string, read-only)
    The ID of this resource.

.createdAt (integer, read-only)
    Timestamp when the resource was created.

.updatedAt (integer, read-only)
    Timestamp when the resource was updated.

.tags (array of string)
    Array of string tags associated with this resource.

.customFields (CustomFieldsDocument)
    Object of case-sensititve key-value pairs of custom fields 
    associated with the resource.

.description (string)
    Friendly description of this resource.

.project (string, read-only)
    ID of the platform project this application belongs to.

.defaultUrl (string)
    The URL where the default client app for this application is 
    deployed.

.appApiKey (string, read-only)
    The API key available to the application.

.defaultRole (string)
    The default Application User role new Application Users 
    created in this application will be given.

.scopes (ScopesDocument)
    Project and user scopes arrays.

{
  "additionalProperties": false,
  "type": "object",
  "description": "An object describing a platform application.",
  "required": ["name", "socialNetworks"],
  "properties": {
    "name": {
      "type": "string",
      "description": "Friendly name of this resource."
    },
    "socialNetworks": {
      "type": "object",
      "description": "An array of social networks that this application will support.",
      "default": {}
    },
    "id": {
      "type": "string",
      "description": "The ID of this resource.",
      "pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
      "readOnly": true
    },
    "createdAt": {
      "type": "integer",
      "description": "Timestamp when the resource was created.",
      "readOnly": true,
      "minimum": 0
    },
    "updatedAt": {
      "type": "integer",
      "description": "Timestamp when the resource was updated.",
      "readOnly": true,
      "minimum": 0
    },
    "tags": {
      "type": "array",
      "description": "Array of string tags associated with this resource.",
      "items": {
        "type": "string",
        "maxLength": 60
      }
    },
    "customFields": {
      "type": "object",
      "description": "Object of case-sensititve key-value pairs of custom fields associated with the resource."
    },
    "description": {
      "type": "string",
      "description": "Friendly description of this resource."
    },
    "project": {
      "type": "string",
      "description": "ID of the platform project this application belongs to.",
      "readOnly": true,
      "pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$"
    },
    "defaultUrl": {
      "type": "string",
      "description": "The URL where the default client app for this application is deployed."
    },
    "appApiKey": {
      "type": "string",
      "description": "The API key available to the application.",
      "readOnly": true,
      "pattern": "^[abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789]{80}$"
    },
    "defaultRole": {
      "type": "string",
      "description": "The default Application User role new Application Users created in this application will be given.",
      "minLength": 13,
      "maxLength": 24
    },
    "scopes": {
      "additionalProperties": false,
      "type": "object",
      "description": "Project and user scopes arrays.",
      "required": ["users", "projects"],
      "properties": {
        "users": {
          "type": "array",
          "description": "An array of Application User IDs this resource is scoped to.",
          "items": { "type": "string" }
        },
        "projects": {
          "type": "array",
          "description": "An array of project IDs this resource is scoped to.",
          "items": {
            "type": "string",
            "description": "The ID of this resource.",
            "pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
            "readOnly": true
          }
        }
      }
    }
  },
  "x-filterable-fields": ["name", "project"]
}

{
  "id": "U4axGkeeeq8r97aaRgBB9fTr",
  "createdAt": 1510053956736,
  "tags": [
    "example",
    "app"
  ],
  "updatedAt": 1510915098055,
  "name": "Consumer Scanning App",
  "description": "An application users can use to scan products.",
  "project": "UmxHK6K8BXsa9KawRh4bTbqc",
  "socialNetworks": {},
  "defaultUrl": "https://google.com",
  "defaultRole": "base_app_user",
  "appApiKey": "a4AjjHgehcKlGaj..."
}

Filterable Fields

This resource type can be filtered using the following fields and operators.

Field	Type	Operators
`name`	String	`=`
`project`	String	`=`

Create an Application

Creates an application within the project specified with projectId.

The object returned contains the appApiKey parameter, which is an Application API key that must be used within an external application to issue calls to the API. However, because this API key can be hard coded within external applications (e.g. mobile/JS) and is visible to anyone, it can be used only for a very limited set of operations (create users, read a product, send actions etc.).

POST /projects/:projectId/applications
Content-Type: application/json
Authorization: $OPERATOR_API_KEY

ApplicationDocument

curl -i -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X POST 'https://$EVT_API_DOMAIN/projects/URG5FDahhBePgNfHVkHTkama/applications' \
  -d '{ 
    "name": "Mobile App", 
    "socialNetworks": {} 
  }'

const projectId = 'URG5FDahhBePgNfHVkHTkama';

const payload = {
  name: 'Consumer Scanning App',
  description: 'An application users can use to scan products.',
  socialNetworks: {},
};

operator.project(projectId).application()
  .create(payload)
  .then(console.log);

String projectId = "URG5FDahhBePgNfHVkHTkama";
HashMap<String, SocialNetwork> networks = new HashMap<String, SocialNetwork>();

Application application = new Application();
application.setName("Consumer Scan App");
application.setDescription("An application users can use to scan products");
application.setSocialNetworks(networks);
apiManager.applicationService().applicationCreator(projectId, application).execute();

HTTP/1.1 201 Created
Content-Type: application/json
Location: https://$EVT_API_DOMAIN/projects/URG5FDahhBePgNfHVkHTkama/applications/UmAFxcdSMt9VE8awRE7dba9n

{
  "id": "UmAFxcdSMt9VE8awRE7dba9n",
  "name": "Consumer Scanning App",
  "project": "URG5FDahhBePgNfHVkHTkama",
  "appApiKey": "cYFWnAiRTaNeOnj8...",
  "description": "An application users can use to scan products",
  "createdAt": 1372243297475,
  "updatedAt": 1372243297475,
  "socialNetworks": {},
  "defaultRole": "base_app_user"
}

Read Applications in a Project

Read a list of applications within the project specified with projectId. The result may be paginated if there are more than 30 items.

GET /projects/:projectId/applications
Authorization: $OPERATOR_API_KEY

curl -H "Authorization: $OPERATOR_API_KEY" \
  -X GET 'https://$EVT_API_DOMAIN/projects/U2meqbNWegsaQKRRaDUmpssr/applications'

const projectId = 'U2meqbNWegsaQKRRaDUmpssr';

operator.project(projectId).application()
  .read()
  .then(console.log);

String projectId = "U2meqbNWegsaQKRRaDUmpssr";

List<Application> apps = apiManager.applicationService().applicationsReader().project(projectId).list().getResult();
for(Application app : apps) {
    System.out.println(app.toString());
}

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": "Umbn56MmBDsatpaawg6XgKfk",
    "name": "Consumer Scanning App",
    "description": "An application users can use to scan products",
    "project": "U2meqbNWegsaQKRRaDUmpssr",
    "appApiKey": "cYFWnAiRTaNeOn...",
    "createdAt": 1372243297475,
    "updatedAt": 1372243297475,
    "socialNetworks": {},
    "defaultRole": "base_app_user"
  }
]

Read an Application

Returns a single application matching the applicationId within the project specified by projectId.

GET /projects/:projectId/applications/:applicationId
Authorization: $OPERATOR_API_KEY

curl -H "Authorization: $OPERATOR_API_KEY" \
  -X GET 'https://$EVT_API_DOMAIN/projects/URG5FDahhBePgNfHVkHTkama/applications/UF3Vqb7D6G8EhMwaRYgQ2pFc'

const projectId = 'URG5FDahhBePgNfHVkHTkama';
const applicationId = 'UF3Vqb7D6G8EhMwaRYgQ2pFc';

operator.project(projectId).application(applicationId)
  .read()
  .then(console.log);

String projectId = "URG5FDahhBePgNfHVkHTkama";
String applicationId = "UF3Vqb7D6G8EhMwaRYgQ2pFc";

Application app = apiManager.applicationService().applicationReader(projectId, applicationId).execute();

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "UF3Vqb7D6G8EhMwaRYgQ2pFc",
  "name": "Consumer Scanning App",
  "description": "An application users can use to scan products",
  "project": "URG5FDahhBePgNfHVkHTkama",
  "appApiKey": "cYFWnAiRTaNeOnj8ej...",
  "createdAt": 1372243297475,
  "updatedAt": 1372243297475,
  "socialNetworks": {},
  "defaultRole": "base_app_user"
}

Update an Application

Update a single application by ID.

PUT /projects/:projectId/applications/:applicationId
Authorization: $OPERATOR_API_KEY
Content-Type: application/json

ApplicationDocument (subset)

curl -i -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X PUT 'https://$EVT_API_DOMAIN/projects/URG5FDahhBePgNfHVkHTkama/applications/UF3Vqb7D6G8EhMwaRYgQ2pFc' \
  -d '{ 
    "name": "Updated App Name" 
  }'

const projectId = 'URG5FDahhBePgNfHVkHTkama';
const applicationId = 'UF3Vqb7D6G8EhMwaRYgQ2pFc';

const update = {
  name: 'Updated App Name'
};

operator.project(projectId).application(applicationId)
  .update(update)
  .then(console.log);

String projectId = "URG5FDahhBePgNfHVkHTkama";
String applicationId = "UF3Vqb7D6G8EhMwaRYgQ2pFc";

// Read an application
Application application = apiManager.applicationService().applicationReader(applicationId).project(projectId).execute();

// Update it
application.setDescription("Updated application description");
apiManager.applicationService().applicationUpdater(projectId, applicationId, application).execute();

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "UF3Vqb7D6G8EhMwaRYgQ2pFc",
  "name": "Updated App Name",
  "project": "URG5FDahhBePgNfHVkHTkama",
  "appApiKey": "cYFWnAiRTaNeOnj8ejc0qQg9FgwyPDV4UXDPQ...",
  "createdAt": 1372243297475,
  "updatedAt": 1372243297475,
  "socialNetworks": {},
  "defaultRole": "base_app_user"
}

Delete an Application

Delete an application by ID. This action cannot be undone.

DELETE /projects/:projectId/applications/:applicationId
Authorization: $OPERATOR_API_KEY

curl -H "Authorization: $OPERATOR_API_KEY" \
  -X DELETE 'https://$EVT_API_DOMAIN/projectId/UmACfDggBDswQpawRk4pAqDq/applications/U3dCCgDYBDswtpawRYBMcnHb'

const projectId = 'UmACfDggBDswQpawRk4pAqDq';
const applicationId = 'U3dCCgDYBDswtpawRYBMcnHb';

operator.project(projectId).application(applicationId)
  .delete();

String projectId = "UmACfDggBDswQpawRk4pAqDq";
String applicationId = "U3dCCgDYBDswtpawRYBMcnHb";

apiManager.applicationService().applicationDeleter(applicationId).project(projectId).execute();

HTTP/1.1 200 OK

Read the Trusted Application API Key

Read the Trusted Application API Key for the application with applicationId. This is a secret key that has access to more endpoints than the standard Application API key.

📘
Note
Operator users with read-only permissions (i.e.: global_read and project_read) will not be able to see this endpoint, or read the Trusted Application API Key.

GET /projects/:projectId/applications/:applicationId/secretKey
Authorization: $OPERATOR_API_KEY

curl -H "Authorization: $OPERATOR_API_KEY" \
  -X GET 'https://$EVT_API_DOMAIN/projects/URG5FDahhBePgNfHVkHTkama/applications/UF3Vqb7D6G8EhMwaRYgQ2pFc/secretKey'

const projectId = 'UG4WExTKBqPr9NwRa3twYDnk';
const applicationId = 'UG4NWfQ7BMPN97wawGQRrxtm';

operator.project(projectId).application(applicationId)
  .secretKey()
  .read()
  .then(console.log);

HTTP/1.1 200 OK
Content-Type: application/json

{
  "secretApiKey": "cYFWnAiRTaNeOnj..."
}

Read Self Application

An application can read its own metadata without knowledge of which project it is in using the /applications/me endpoint with its Application API key.

GET /applications/me
Authorization: $APPLICATION_API_KEY

curl -H "Authorization: $APPLICATION_API_KEY" \
  -X GET 'https://$EVT_API_DOMAIN/applications/me'

const apiKey = 'APPLICATION_API_KEY';

evrythng.api({
  url: '/applications/me',
  apiKey
}).then(console.log);

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "UmSMbD9ACTtn99aaa2gfnKgp",
  "createdAt": 1495013107545,
  "customFields": {},
  "updatedAt": 1495013620339,
  "name": "Consumer Scanning App",
  "description": "An application users can use to scan products",
  "project": "UGSMSDs5fc9n9QaRwkXC4pDg",
  "socialNetworks": {},
  "appApiKey": "gxQiaD7gwHiuyCIex..."
}

Update Self Application

The /applications/me endpoint can also be used to allow an application to update its own meta data using its Trusted Application API Key.

PUT /applications/me
Content-Type: application/json
Authorization: $TRUSTED_APPLICATION_API_KEY

ApplicationDocument (subset)

curl -i -H "Content-Type: application/json" \
  -H "Authorization: $TRUSTED_APPLICATION_API_KEY" \
  -X PUT 'https://$EVT_API_DOMAIN/applications/me' \
  -d '{ 
		"customFields": {
      "somekey": "somevalue"
    }
  }'

const apiKey = 'TRUSTED_APPLICATION_API_KEY';
const payload = { tags: ['updated'] };

evrythng.api({
  url: '/applications/me',
  apiKey,
  method: 'put',
  data: payload,
}).then(console.log);

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "UGf5HamGBDPa95waah7Can5c",
  "createdAt": 1499177113975,
  "updatedAt": 1510565887701,
  "name": "Consumer Scanning App",
  "description": "An application users can use to scan products.",
  "project": "UmxHK6K8BXsa9KawRh4bTbqc",
  "tags": ["updated"],
  "socialNetworks": {},
  "defaultRole": "base_app_user",
  "appApiKey": "gXHaJVTBUrgYS3gDqVoy06WqXNM4zeGU..."
}