API - App requests¶

Hint

While this documentation uses dummy names like config_1, info_1, etc., you are free to choose the ID of the values yourself as long as they contain only letters from a-z, numbers 0-9 and the underscore

/apps¶

The app component consists of the following fields:

app fields

appId

integer the unique identifier this entity belongs to

templateId

integer the template this app points to

companyId

integer id of the owning company

lang

string the default language code. Syntax: de_DE for Germany, de_AT for Austrian german ...

name

string give this entity a name

activated

bool the status of the app

expiryDate

string the date until the app is running or integer the number of days the app is running

common fields

created

dateTime the date this entity was created

updated

dateTime the date this entity was modified

createdFromIp

string the IP of the creator of this entity

updatedFromIp

string the IP of the person modifying this entity

createdBy

string the username or apikeyId of the creator of this entity

updatedBy

string the username or apikeyId of the person modifying this entity

deletedAt

the entity got deleted when this field contains a dateTime, otherwise this field contains null

relations

company*, template*, channels, configs, translations, infos, languages*

* can be fetched via collection request

GET /apps¶

Receive a collection of apps owned by your company.

Query parameters

page
items
fields
exclude
orderasc/orderdesc
rel

Example response body¶

{
  "_links": {
    "next": {
      "href": "https://my.app-arena.com/api/v2/apps?page=2"
    },
    "self": {
      "href": "https://my.app-arena.com/api/v2/apps"
    }
  },
  "_embedded": {
    "data": {
      "1": {
        "appId": 1,
        "name": "Example app",
        "lang": "en_US",
        "activated": true,
        "expiryDate": "2016-11-30 00:00:00",
        "companyId": 1,
        "templateId": 888,
        "_links": {
          "app": {
            "href": "https://my.app-arena.com/api/v2/apps/1"
          },
          "appLanguage": {
            "href": "https://my.app-arena.com/api/v2/apps/1/languages/en_US"
          },
          "company": {
            "href": "https://my.app-arena.com/api/v2/companies/1"
          },
          "template": {
            "href": "https://my.app-arena.com/api/v2/templates/888"
          }
        }
      },
      "2": {
        "appId": 2,
        "name": "Example app 2",
                .
                .
                .
      },
      "3": {
                .
                .
                .
      },
        .
        .
        .
      "N": {
                .
                .
                .
      }
    }
  },
  "total_items": 1000,
  "page_size": 20,
  "page_count": 50,
  "page_number": 1
}

GET /apps/:appId¶

Receive information about an app entity specified by :appId

Query parameters

fields
exclude
rel

Example response body

{
  "_embedded": {
    "data": {
      "appId": 1,
      "name": "Example app",
      "lang": "de_DE",
      "activated": false,
      "expiryDate": "2099-01-01 00:00:00",
      "companyId": 1,
      "templateId": 888,
      "_links": {
        "app": {
          "href": "https://my.app-arena.com/api/v2/apps/1"
        },
        "appLanguage": {
          "href": "https://my.app-arena.com/api/v2/apps/1/languages/de_DE"
        },
        "company": {
          "href": "https://my.app-arena.com/api/v2/companies/1"
        },
        "template": {
          "href": "https://my.app-arena.com/api/v2/templates/888"
        }
      }
    }
  }
}

POST /apps¶

Creates a new app

Query parameters

force

Example request body¶

{
    "templateId"    :   888,
    "name"          :   "created example app",
    "expiryDate"    :   60,
    "lang"          :   "de_DE"
}

Example response body

{
  "status": 201,
  "data": {
    "appId": 1,
    "templateId": 888,
    "companyId": 1,
    "lang": "de_DE",
    "name": "created example app",
    "activated": false,
    "expiryDate": "2016-08-26 10:39:00"
  }
}

Required data

name: string give this entity a name
templateId: integer The template ID this app is connected to
lang: string the default language code. Syntax: de_DE for Germany, de_AT for Austrian german ...

Optional data

companyId

integer The ID of the owning company, if not specified, the app will be owned by the company used for authorization

expiryDate

Integer: Sets the number of days the app is valid, 0 sets the app valid for 50 years.
String: Sets a date for app expiration, needs to be in the format ‘Y-m-d H:i:s’ with Y=year, m=month, d=day, H=hour, i=minute, s=second

activated

bool the status of the app

Copy an existing app¶

If you want to modify an existing template but keep the original, you can copy it by sending a POST request with the field “copyFrom” : “template” and the templateId

POST /apps¶

Example request body

{
    "copyFrom"      : 1
}

Example response body

{
  "status": 201,
  "data": {
    "appId": 2,
    "templateId": 1,
    "companyId": 1,
    "lang": "de_DE",
    "name": "App name [copy]",
    "activated": true,
    "expiryDate": "2016-10-03 13:16:52"
  }
}

Required data

copyFrom: integer``|``string sets the app ID which is to be copied

Optional data

templateId: integer sets the template the new app is pointing to
companyId: integer sets a different company than your own as owner of the newly created app
expiryDate: string sets the expiration date of the app integer sets the expiration date in days. A value of 30 means that the app will expire in 30 days from the day of execution
lang: string sets the default language of the new app. This language must be present in the root project
name: string defines the name of the new app. If not specified, the name of the original app with an additional “[copy]” string is used
activated: bool sets the activation status of the new app

PUT /apps/:appId¶

Alters an app entry specified by :appId

Query parameters

force

Example request body

{
    "activated"    :   true,
}

Example response body

{
  "status": 200,
  "data": {
    "appId": 1,
    "templateId": 888,
    "companyId": 1,
    "lang": "de_DE",
    "name": "created Example app",
    "activated": true,
    "expiryDate": "2016-08-26 10:39:00"
  }
}

modifiable parameters

templateId

integer The template ID this app is connected to

name

string give this entity a name

activated

bool the status of the app

expiryDate

Integer: Sets the number of days the app is valid, 0 sets the app valid for 50 years.
String: Sets a date for app expiration, needs to be in the format ‘Y-m-d H:i:s’ with Y=year, m=month, d=day, H=hour, i=minute, s=second

DELETE /apps/:appId¶

Deletes an app from the database specified by :appId

Warning

This deletes all contained settings and translations as well!

Query parameters

none

Example response body

{
  "status": 200,
  "message": "app '1' deleted."
}

/apps/:appId/configs¶

The app config component consists of the following fields:

app config fields

appId/templateId/projectId

integer the unique identifier this entity belongs to

configId

string the unique identifier for this entity

lang

string the default language code. Syntax: de_DE for Germany, de_AT for Austrian german ...

type

string has to be one of “facebook”, “domain” or “website”

name

string give this entity a name

value

string the currently selected config entity content

description

string an informational description of the purpose of this entity, displayed to the user

meta

string additional information in custom format. See config meta section for information about the behaviour of meta data

common fields

revision

integer instead of modifying an existing entity, a new entity is created while the revision reflects its actuality -> The highest revision marks the currently used entity

created

dateTime the date this entity was created

createdFromIp

string the IP of the creator of this entity

createdBy

string the username or apikeyId of the creator of this entity

deletedAt

the entity got deleted when this field contains a dateTime, otherwise this field in null

GET /apps/:appId/configs¶

Receive a collection of config values of an app specified by :appId

Query parameters

fields
exclude
lang

Example response body

{
  "_links": {
    "self": {
      "href": "http://my.app-arena.com/api/v2/apps/1/configs"
    }
  },
  "_embedded": {
    "data": {
      "config_1": {
        "configId": "config_1",
        "lang": "de_DE",
        "name": "config value 1",
        "revision": 0,
        "value": "some_value",
        "meta": {"meta_key":{"meta_inner":"meta_inner_value"}},
        "type": "input",
        "description": "This is an example of a app config value.",
        "appId": 1,
        "_links": {
          "app": {
            "href": "http://my.app-arena.com/api/v2/apps/1"
          },
          "config": {
            "href": "http://my.app-arena.com/api/v2/apps/1/configs/config_1"
          }
        }
      },
      "config_2": {
        "configId": "config_2",
            .
            .
            .
        }
      },
            .
            .
            .
      }
    }
  }
}

GET /apps/:appId/configs/:configId¶

Receive the information of a config value entity of an app specified by :appId and :configId

Query parameters

fields
exclude
lang

Example response body

{
  "_embedded": {
    "data": {
      "configId": "config_1",
      "lang": "de_DE",
      "name": "config value 1",
      "revision": 0,
      "value": "some_value",
      "meta": {
        "meta_key": {
          "meta_inner": "meta_inner_value"
        }
      },
      "type": "input",
      "description": "This is an example of a app config value.",
      "appId": 1,
      "_links": {
        "app": {
          "href": "http://my.app-arena.com/api/v2/apps/1"
        },
        "config": {
          "href": "http://my.app-arena.com/api/v2/apps/1/configs/config_1"
        }
      }
    }
  }
}

PUT /apps/:appId/configs/:configId¶

Alter a config value for an app specified by :appId and :configId

Query parameters

lang

Example request body

{
    "value"    :   "new value"
}

Example response body

{
  "status": 200,
  "data": {
    "appId": 1,
    "configId": "config_1",
    "lang": "de_DE",
    "type": "input",
    "name": "config value 1",
    "value": "new value",
    "description": "This is an example of a app config value.",
    "revision": 1,
    "meta": {"meta_key":{"meta_inner":"meta_inner_value"}}
  }
}

modifiable parameters

value: string the currently selected config content. See config for more information
name: string give this entity a name
description: string an informational description of the purpose of this entity, displayed to the user
meta: string additional information in custom format. See config meta section for information about the behaviour of meta data

DELETE /apps/:appId/configs/:configId¶

Deletes a config value of an app from the database specified by :appId and :configId

Query parameters

lang

Example response body

{
  "status": 200,
  "message": "Config 'config_1' deleted."
}

/apps/:appId/infos¶

The app info component consists of the following fields:

app info fields

appId/templateId/projectId

integer the unique identifier this entity belongs to

info_id

string the unique identifier for this entity

lang

string the default language code. Syntax: de_DE for Germany, de_AT for Austrian german ...

value

string the currently selected config entity content

meta

string additional information in custom format. See config meta section for information about the behaviour of meta data

common fields

revision

integer instead of modifying an existing entity, a new entity is created while the revision reflects its actuality -> The highest revision marks the currently used entity

created

dateTime the date this entity was created

createdFromIp

string the IP of the creator of this entity

createdBy

string the username or apikeyId of the creator of this entity

deletedAt

the entity got deleted when this field contains a dateTime, otherwise this field in null

GET /apps/:appId/infos¶

Receive a collection of info values of an app specified by :appId

Query parameters

fields
exclude
lang

Example response body

{
  "_links": {
    "self": {
      "href": "http://my.app-arena.com/api/v2/apps/1/infos"
    }
  },
  "_embedded": {
    "data": {
      "info_1": {
        "infoId": "info_1",
        "lang": "de_DE",
        "revision": 0,
        "value": "some_value",
        "meta": {"meta_key":{"meta_inner":"meta_inner_value"}},
        "description": "This is an example of an app info value.",
        "appId": 1,
        "_links": {
          "app": {
            "href": "http://my.app-arena.com/api/v2/apps/1"
          },
          "info": {
            "href": "http://my.app-arena.com/api/v2/apps/1/infos/info_1"
          }
        }
      },
      "info_2": {
        "infoId": "info_2",
            .
            .
            .
        }
      },
            .
            .
            .
      }
    }
  }
}

GET /apps/:appId/infos/:infoId¶

Receive the information of an info entity of an app specified by :appId and :infoId

Query parameters

fields
exclude
lang

Example response body

{
  "_embedded": {
    "data": {
      "infoId": "info_1",
      "lang": "de_DE",
      "revision": 0,
      "value": "1234",
      "templateId": 888,
      "meta": {
        "type": "integer"
      },
      "_links": {
        "info": {
          "href": "http://my.app-arena.com/api/v2/apps/1/infos/info_1"
        },
        "template": {
          "href": "http://my.app-arena.com/api/v2/templates/888"
        }
      }
    }
  }
}

PUT /apps/:appId/infos/:infoId¶

Alter a info value for an app specified by :appId and :infoId

Query parameters

lang

Example request body

{
    "value"    :   "new value"
}

Example response body

{
  "status": 200,
  "data": {
    "appId": 1,
    "infoId": "info_1",
    "lang": "de_DE",
    "revision": 1,
    "value": "new value",
    "meta": {"type":"string"}
  }
}

modifiable parameters

value: string the currently selected config content. See config for more information
meta: string additional information in custom format. See config meta section for information about the behaviour of meta data

DELETE /apps/:appId/infos/:infoId¶

Deletes a info value of an app from the database specified by :appId and :infoId

Query parameters

lang

Example response body

{
  "status": 200,
  "message": "Info 'info_1' in app '1' deleted."
}

/apps/:appId/languages¶

The app language component consists of the following fields:

app language fields

appId/projectId

integer the unique identifier this entity belongs to

lang

string the default language code. Syntax: de_DE for Germany, de_AT for Austrian german ...

common fields

created

dateTime the date this entity was created

updated

dateTime the date this entity was modified

createdFromIp

string the IP of the creator of this entity

updatedFromIp

string the IP of the person modifying this entity

createdBy

string the username or apikeyId of the creator of this entity

updatedBy

string the username or apikeyId of the person modifying this entity

deletedAt

the entity got deleted when this field contains a dateTime, otherwise this field contains null

Note

Activated languages always belong to the app while the available languages derive from the corresponding project.

GET /apps/:appId/languages¶

Receive information about the available and activated languages specified by :appId

Query parameters

none

Example response body

{
  "activated": {
    "de_DE": {
      "lang": "de_DE",
      "appId": 1
    }
  },
  "available": {
    "de_DE": {
      "lang": "de_DE",
      "projectId": 1,
      "version": "1.1.0"
    },
    "en_US": {
      "lang": "en_US",
      "projectId": 1,
      "version": "1.1.0"
    }
  }
}

POST /apps/:appId/languages¶

Activate a language in an app specified by :appId and :lang

Query parameters

none

Example request body

{
    "lang"  : "en_US"
}

Example response body

{
  "status": 201,
  "data": {
    "appId": 1,
    "lang": "en_US",
  }
}

required data

lang: string the default language code. Syntax: de_DE for Germany, de_AT for Austrian german ...

/apps/:appId/translations¶

The app translation component consists of the following fields:

app translation fields

translationId

string the unique identifier for this entity

lang

string the default language code. Syntax: de_DE for Germany, de_AT for Austrian german ...

appId

integer the unique identifier this entity belongs to

translated

bool shows if the string is translated (singular translation)

translation

string the translated string (singular translation)

pluralized

bool shows if the string is translated (plural translation)

translationPluralized

string the translated string (plural translation)

common fields

revision

integer instead of modifying an existing entity, a new entity is created while the revision reflects its actuality -> The highest revision marks the currently used entity

created

dateTime the date this entity was created

createdFromIp

string the IP of the creator of this entity

createdBy

string the username or apikeyId of the creator of this entity

deletedAt

the entity got deleted when this field contains a dateTime, otherwise this field in null

GET /apps/:appId/translations¶

Receive translations of an app specified by :appId

Query parameters

lang
fields
exclude
orderasc/orderdesc

Example response body

{
  "_links": {
    "self": {
      "href": "http://my.app-arena.com/api/v2/apps/1/translations"
    }
  },
  "_embedded": {
    "data": {
      "translation_1": {
        "translationId": "translation_1",
        "lang": "de_DE",
        "revision": 0,
        "translation": "translated_text",
        "translated": true,
        "translationPluralized": "translation_pluralized_text",
        "pluralized": true,
        "projectId": 1,
        "version": "1.1.0"
        "_links": {
          "version": {
            "href": "http://my.app-arena.com/api/v2/projects/1/versions/1"
          }
        }
      },
      "translation_2": {
        "translationId": "translation_2",
            .
            .
            .
      },
      "translation_3":{
            .
            .
            .
      },
        .
        .
        .
      "translation_N":{
            .
            .
            .
      }
    }
  }
}

PUT /apps/:appId/translations/:translationId¶

Change a translation for an app specified by :appId and :infoId

Query parameters

lang

Example request body

{
    "translation": "new translation"
}

Example response body

{
  "status": 200,
  "data": {
    "translationId": "translation_1",
    "lang": "de_DE",
    "appId": 1,
    "translation": "new translation",
    "translated": true,
    "translation_pluralized": "translation_pluralized_text",
    "pluralized": true,
    "revision": 1
  }
}

modifiable parameters

translation: string the translated string (singular translation)
translated: bool shows if the string is translated (singular translation)
translationPluralized: string the translated string (plural translation)
pluralized: bool shows if the string is translated (plural translation)

DELETE /apps/:appId/translations/:translationId¶

Deletes a translation of an app specified by :appId and :infoId

Query parameters

lang

Example response body

{
  "status": 200,
  "message": "Translation 'translation_1' deleted."
}

/apps/:appId/channels¶

Note

A Channel needs to be connected to an App in order to publish that App through it

GET /apps/:appId/channels¶

Returns a list of channels, this app has been published on.

Query parameters

none

Example response body

{
  "_links": {
    "self": {
      "href": "https://my.app-arena.com/api/v2/apps/18560/channels"
    }
  },
  "_embedded": {
    "data": [
      {
        "channelId": 6753,
        "companyId": 1,
        "type": "facebook",
        "name": "App-Arena Test Page 01",
        "value": "254789607927209",
        "_links": {
          "company": {
            "href": "https://my.app-arena.com/api/v2/companies/1"
          }
        }
      },
      ...
    ]
  }
}

POST /apps/:appId/channels¶

Connects an App with an existing channel of your company

Query parameters

none

Example request body

{
    "channelId": 1
}

Example response body

{
  "status": 201,
  "data": {
      "channelId": 1,
      "companyId": 1,
      "type": "domain",
      "name": "my domain channel",
      "value": "www.mydomain.com",
      "meta": {}
  }
}

Required data

channelId: integer the channel you want to connect this app to

DELETE /apps/:appId/channels/:channelId¶

Removes a channel from an App

Query parameters

none

Example response body

[

{: “channelId”: 1, “companyId”: 1, “type”: “domain”, “name”: “my domain channel”, “value”: “ww.mydomain.com”, “meta”: {}

}

]

Example response body

{
  "status": 201,
  "message": "Channel '10' of app '13784' removed"
}