API - Project 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 alphanumerics and the underscore

The version concept¶

As you can see in image 1 of the structure chapter, all versions point to a root project. This was introduced in order to give every application a home instead of letting them coexist on the same level, which can lead to long unordered lists when displaying. With this approach, the list of existing projects is slimmed down drastically while keeping everything nicely accessible.

In order to work on a specific version, the project routes are used while the version can be selected through the query parameter ‘version’.

Example: GET /projects/1/configs?version=2.1.0 will return all config entries of the version ‘2.1.0’ of project ‘1’

If no version query parameter is defined, the API automatically determines the highest version and performs the requested action on it.

The format of the version-number is based on semantic versioning. It is stored in a string and consists of three integers in the format ‘Ma.Mi.P’, where Ma stands for ‘MAJOR’, Mi for ‘MINOR’ and P for ‘PATCH’.

Recommended usage is that you increment the:

MAJOR version when you make incompatible changes,

MINOR version when you add functionality in a backwards-compatible manner, and

PATCH version when you make backwards-compatible bug fixes.

/projects¶

The project component consists of the following fields:

project fields

projectId

integer the unique identifier this entity belongs to

companyId

integer the id of the owning company

name

string give this entity a name

description

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

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 for project requests (/projects[/:projectId])

company*, versions*

relations for version requests (/projects/:projectId/versions[/:versionId])

company*, project*, configs, translations, infos, languages*

* can be fetched via collection request

GET /projects¶

Receive a collection of projects owned by your company.

Query parameters

page
items
fields
exclude
orderasc/orderdesc
rel

Example response body¶

{
  "_links": {
    "next": {
      "href": "http://my.app-arena.com/api/v2/projects?page=2"
    },
    "self": {
      "href": "http://my.app-arena.com/api/v2/projects"
    }
  },
  "_embedded": {
    "data": {
      "1": {
        "projectId": 1,
        "name": "Project_1",
        "description": "This is a project description",
        "companyId": 1,
        "_links": {
          "project": {
            "href": "http://my.app-arena.com/api/v2/projects/1"
          },
          "company": {
            "href": "http://my.app-arena.com/api/v2/companies/1"
          }
        }
      },
      "2": {
        "projectId": 2,
                .
                .
                .
      },
        .
        .
        .
      "N":{
                .
                .
                .
      }
    }
  },
  "total_items": 100,
  "page_size": 20,
  "page_count": 5,
  "page_number": 1
}

GET /projects/:projectId¶

Receive information about a project entity specified by :projectId

Query parameters

fields
exclude
rel

Example response body

{
  "_embedded": {
    "data": {
      "projectId": 1,
      "name": "Project_1 name",
      "description": "This is s project description",
      "companyId": 1,
      "_links": {
        "project": {
          "href": "http://my.app-arena.com/api/v2/projects/1"
        },
        "company": {
          "href": "http://my.app-arena.com/api/v2/companies/1"
        }
      }
    }
  }
}

POST /projects¶

Creates a new project

Note

When creating a new project, a version ‘1.0’ and the specified language will be created as well.

Query parameters

force

Example request body¶

{
    "name"      : "new project",
    "lang"      : "de_DE"
}

Example response body

{
  "status": 201,
  "data": {
    "projectId": 2,
    "companyId": 1,
    "name": "new project",
    "description": null,
    "version": {
      "projectId": 1,
      "version": "1.1.0"
      "projectId": 2,
      "companyId": 1,
      "name": "autogenerated initial version of project 'new project'.",
      "lang": "de_DE",
      "variant": 1,
      "public": false,
      "language": {
        "projectId": 1,
        "version": "1.1.0"
        "lang": "de_DE",
      }
    }
  }
}

Tip

You can change the name of the initial version with a PUT request to /projects/:projectId/versions/1.0

Required data

name

string give this entity a name

lang

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

sets the default language of the initial project version and makes the language available to all connected templates/apps

Optional data

companyId: integer the id of the owning company
description: string an informational description of the purpose of this entity, displayed to the user

Copy an existing project¶

This request makes a copy of an existing project. You can set

POST /projects¶

Example request body

{
    "copyFrom"  : 1,
    "version"   : "1.0.0"
}

Example response body

{
  "status": 201,
  "data": {
    "projectId": 2,
    "companyId": 1,
    "name": "dummy project [copy]",
    "description": null
  }
}

Required data

copyFrom

integer``|``string sets the project ID which is to be copied

version

string: "all" copies all existing versions of the project
"latest" copies the most recent version of the project
"X.Y.Z" copies the specified version of the project
["A.B.C","X.Y.Z",...] copies all the declared versions of the project

Optional data

companyId: integer defines a different company than your own as owner of the newly created template
name: string defines the name of the new project. If not specified, the name of the original project with an additional “[copy]” string is used
description: string describe the newly created project

PUT /projects/:projectId¶

Alters an project entry specified by :projectId

Query parameters

force

Example request body

{
    "name":         "new project name",
    "description":  "This is a new project description"
}

Example response body

{
  "status": 200,
  "data": {
    "projectId": 2,
    "companyId": 1,
    "name": "new project name",
    "description": "This is a new project description"
  }
}

modifiable parameters

name: string give this entity a name
companyId: integer the id of the owning company
description: string an informational description of the purpose of this entity, displayed to the user

DELETE /projects/:projectId¶

Deletes an project from the database specified by :projectId

Warning

This deletes all versions including all contained settings and translations as well!

Query parameters

none

Example response body

{
  "status": 200,
  "message": "Project '2' deleted."
}

/projects/:projectId/versions¶

Note

Every request regarding a version of a project uses ‘projectId’ and ‘version’ fields for indication. When handling the actual version entities, the field ‘variant’ is used.

The version component consists of the following fields:

version fields

projectId

integer the unique identifier this entity belongs to

companyId

integer the 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

variant

string the version number (is called ‘variant’ only in the version itself, all other components call this field ‘version’)

public

bool determines if the template may be used by users of foreign companies

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

GET /projects/:projectId/versions¶

Receive information about the versions of a project specified by :project_id

Query parameters

page
items
fields
exclude
orderasc/orderdesc
rel

Example response body

{
  "_links": {
    "self": {
      "href": "http://my.app-arena.com/api/v2/projects/1/versions"
    },
    "next": {
      "href": "http://my.app-arena.com/api/v2/projects/1/versions?page=2"
    },
  },
  "_embedded": {
    "data": {
      "1.0.0": {
        "projectId": 1,
        "name": "project version 1.0.0",
        "variant": "1.0.0",
        "public": false,
        "lang": "de_DE",
        "companyId": 1,
        "projectId": 1,
        "_links": {
          "version": {
            "href": "http://my.app-arena.com/api/v2/projects/1/versions/1.0"
          },
          "company": {
            "href": "http://my.app-arena.com/api/v2/companies/1"
          },
          "project": {
            "href": "http://my.app-arena.com/api/v2/projects/1"
          }
        }
      },
      "1.1.0": {
        "projectId": 2,
        "version": "1.1.0",
                .
                .
                .
      },
        .
        .
        .
      "M.m.P": {
                .
                .
                .
      }
    }
  },
  "total_items": 10,
  "page_size": 5,
  "page_count": 1,
  "page_number": 1
}

GET /projects/:projectId/versions/:version¶

Receive information about a project version specified by :projectId and :version

Note

Use the version number as :version e.g.: GET /projects/1/versions/1.1.0

Query parameters

fields
exclude
rel

Example response body

{
  "_embedded": {
    "data": {
      "name": "project version 1.1.0",
      "variant": "1.1.0",
      "public": false,
      "lang": "de_DE",
      "companyId": 1,
      "projectId": 1,
      "_links": {
        "version": {
          "href": "http://my.app-arena.com/api/v2/projects/1/versions/1.1"
        },
        "company": {
          "href": "http://my.app-arena.com/api/v2/companies/1"
        },
        "project": {
          "href": "http://my.app-arena.com/api/v2/projects/1"
        }
      }
    }
  }
}

POST /projects/:projectId/versions¶

Create a new version for a project, specified by :projectId

Note

The default language specified in the request body will be created automatically and is included in the response under the ‘language’ sub-object!

Query parameters

force

Example request body

{
    "name"      : "new project version",
    "lang"      : "de_DE"
}

Example response body

{
  "status": 200,
  "data": {
    "projectId": 1,
    "companyId": 1,
    "name": "new project version",
    "lang": "de_DE",
    "variant": "1.2.0",
    "public": false,
    "language": {
      "projectId": 3,
      "version": "1.2.0"
      "lang": "de_DE",
    }
  }
}

Required data

name: string give this entity a name
lang: string the default language code. Syntax: de_DE for Germany, de_AT for Austrian german ...

Optional data

variant: string the version number (is called ‘variant’ only in the version itself, all other components call this field ‘version’)
public: bool determines if the template may be used by users of foreign companies

Copy an existing version¶

Copies a version inside a project specified by :projectId

POST /projects/:projectId/versions¶

Example request body

{
    "copyFrom"  : "1.0.0"
}

Example response body

{
  "status": 201,
  "data": {
    "projectId": 1,
    "variant": "1.0.1",
    "companyId": 1,
    "name": "dummy version of project 1 [copy]",
    "lang": "de_DE",
    "public": false
  }
}

Required data

copyFrom: string specifies the version which is to be copied

Optional data

name: string defines the name of the new version. If not specified, the name of the original version with an additional “[copy]” string is used
lang: string sets the default language of the new version
variant: string sets the version variant number (“A.B.C”) of the new version. If not submitted, the last digit is increased by one
public: bool sets the public status of the new version

PUT /projects/:projectId/versions/:version¶

Alters the properties of a version, specified by :projectId and :version

Query parameters

none

Example request body

{
    "name"      : "new version name"
}

Example response body

{
  "status": 200,
  "data": {
    "projectId": 1,
    "companyId": 1,
    "name": "new version name",
    "lang": "de_DE",
    "variant": "1.2.0",
    "public": false
  }
}

modifiable parameters

name: string give this entity a name
public: bool determines if the template may be used by users of foreign companies

DELETE /projects/:projectId/versions/:version¶

Deletes a version of an project from the database specified by :projectId and :version

Warning

This deletes all containing settings and translations of the version as well!

Query parameters

lang

Example response body

{
  "status": 200,
  "message": "Version '111' deleted."
}

/projects/:projectId/configs¶

The project config component consists of the following fields:

project config fields

projectId

integer the unique identifier this entity belongs to

version

string the version number, format: “Ma.Mi.P” Ma=Major, Mi=Minor, P=Patch e.g.: “2.0.3”

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

Note

For all of the following requests, the query ‘version’ can be used to select a specific project-version. If it is left blank the operation will automatically use the most recent version

GET /projects/:projectId/configs¶

Receive a collection of config values of an project specified by :projectId

Query parameters

fields
exclude
lang
version

Example response body

{
  "_links": {
    "self": {
      "href": "http://my.app-arena.com/api/v2/projects/1/configs"
    }
  },
  "_embedded": {
    "data": {
      "config_1": {
        "configId": "config_1",
        "lang": "de_DE",
        "revision": 0,
        "type": "input",
        "name": "project config_1 name",
        "value": "some_value",
        "meta": {"meta_key":{"meta_inner":"meta_inner_value"}},
        "description": "This is a config value description",
        "projectId": 1,
        "version": "1.1.0"
        "_links": {
          "version": {
            "href": "http://my.app-arena.com/api/v2/projects/1/versions/1.0"
          }
        }
      },
      "config_2": {
        "configId": "config_2",
                .
                .
                .
      },
        .
        .
        .
      "config_N": {
                .
                .
                .
      }
    }
  }
}

GET /projects/:projectId/configs/:configId¶

Receive the information of a config value entity of a project specified by :templateId and :configId

Query parameters

fields
exclude
lang

Example response body

{
  "_embedded": {
    "data": {
      "configId": "bla",
      "lang": "de_DE",
      "revision": 0,
      "type": "input",
      "name": "bla",
      "value": "lala",
      "meta": null,
      "description": null,
      "projectId": 1,
      "version": "1.1.0",
      "_links": {
        "version": {
          "href": "http://my.app-arena.com/api/v2/projects/111/versions/384"
        }
      }
    }
  }
}

POST /projects/:projectId/configs¶

Creates a new config value

Query parameters

force

Example request body

{
    "name"      : "new config",
    "configId"  : "text_content",
    "type"      : "input"
}

Example response body

{
  "status": 201,
  "data": {
    "projectId": 1,
    "version": "1.1.0"
    "configId": "text_content",
    "lang": "de_DE",
    "type": "input",
    "name": "new config",
    "value": null,
    "description": null,
    "meta": null,
    "revision": 0
  }
}

Required data

name: string give this entity a name
configId: string the unique identifier for this entity
type: string has to be one of “facebook”, “domain” or “website”

Optional data

value: string the currently selected config content. See config for more information
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
lang: string the default language code. Syntax: de_DE for Germany, de_AT for Austrian german ...

PUT /projects/:projectId/configs/:configId¶

Alters the properties of a project config entry specified by :projectId and :configId

Query parameters

lang

version

Example request body

{
    "name":         "new config name",
    "meta_example": "meta_content",
}

Example response body

{
  "status": 200,
  "data": {
    "projectId": 1,
    "version": "1.1.0"
    "configId": "config_1",
    "lang": "de_DE",
    "type": "input",
    "name": "new config name",
    "value": "some_value",
    "description": null,
    "meta": "{\"meta_example\":\"meta_content\"}",
    "revision": 2
  }
}

modifiable parameters

description: string an informational description of the purpose of this entity, displayed to the user
name: string give this entity a name
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

DELETE /projects/:projectId/configs/:configId¶

Deletes a config entry of an project from the database specified by :projectId and :configId

Query parameters

lang

Example response body

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

/projects/:projectId/infos¶

The project info component consists of the following fields:

project info fields

projectId

integer the unique identifier this entity belongs to

version

string the version number, format: “Ma.Mi.P” Ma=Major, Mi=Minor, P=Patch e.g.: “2.0.3”

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 /projects/:projectId/infos¶

Receive the collection of info values of a project specified by :projectId

Query parameters

fields
exclude
lang

Example response body

{
  "_links": {
    "self": {
      "href": "http://my.app-arena.com/api/v2/projects/1/infos"
    }
  },
  "_embedded": {
    "data": {
      "info_1": {
        "infoId": "info_1",
        "lang": "de_DE",
        "revision": 1,
        "value": "some_value",
        "projectId": 1,
        "version": "1.1.0"
        "meta": null,
        "_links": {
          "version": {
            "href": "http://my.app-arena.com/api/v2/projects/1/versions/1.0"
          }
        }
      },
      "info_2": {
        "infoId": "info_2",
                .
                .
                .
      },
        .
        .
        .
      "info_N": {
                .
                .
                .
      }
    }
  }
}

GET /projects/:projectId/infos/:infoId¶

Receive the information of an info entity of an project specified by :projectId and :infoId

Query parameters

fields
exclude
lang

Example response body

{
  "_embedded": {
    "data": {
      "infoId": "info_1",
      "lang": "de_DE",
      "revision": 1,
      "value": "some_value",
      "projectId": 1,
      "version": "1.1.0",
      "meta": {
        "type": "string"
      },
      "_links": {
        "version": {
          "href": "http://my.app-arena.com/api/v2/projects/1/versions/1.0"
        }
      }
    }
  }
}

POST /projects/:projectId/infos¶

Creates a new info entry

Query parameters

force

Example request body

{
    "name"      : "new info name",
    "infoId"    : "new info",
    "lang"      : "de_DE",
    "metakey"   : "metavalue"
}

Example response body

{
  "status": 200,
  "data": {
    "projectId": 1,
    "version": "1.1.0"
    "infoId": "new info",
    "lang": "de_DE",
    "value": null,
    "meta": {"metakey": "metavalue"},
    "revision": 0
  }
}

Required data

infoId: string the unique identifier for this entity

Optional data

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
lang: string the default language code. Syntax: de_DE for Germany, de_AT for Austrian german ...

PUT /projects/:projectId/infos/:infoId¶

Alter a info value for an project specified by :projectId and :infoId

Query parameters

lang

Example request body

{
    "value":   "new value"
}

Example response body

{
  "status": 200,
  "data": {
    "projectId": 1,
    "version": "1.1.0"
    "infoId": "info_1",
    "lang": "de_DE",
    "value": "new value",
    "meta": "{\"type\":\"string\"}",
    "revision": 2
  }
}

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 /projects/:projectId/infos/:infoId¶

Deletes a info value of an project from the database specified by :projectId and :infoId

Query parameters

lang

Example response body

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

/projects/:projectId/languages¶

The project language component consists of the following fields:

project language fields

projectId

version

string the version number, format: “Ma.Mi.P” Ma=Major, Mi=Minor, P=Patch e.g.: “2.0.3”

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

GET /projects/:projectId/languages¶

Receive information about the available languages specified by :projectId

Query parameters

none

Example response body

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

POST /projects/:projectId/languages¶

Activate a language in an project specified by :projectId and :lang

Query parameters

none

Example request body

{
    "lang"  : "en_US"
}

Example response body

{
  "status": 201,
  "data": {
    "projectId": 1,
    "version": "1.1.0"
    "lang": "en_US"
  }
}

required data

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

/projects/:projectId/translations¶

The template translation component consists of the following fields:

template translation fields

translationId

string the unique identifier for this entity

version

string the version number, format: “Ma.Mi.P” Ma=Major, Mi=Minor, P=Patch e.g.: “2.0.3”

lang

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

projectId

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 /projects/:projectId/translations¶

Receive translations of a project specified by :projectId

Query parameters

lang
fields
exclude
orderasc/orderdesc

Example response body

{
  "_links": {
    "self": {
      "href": "http://my-app-arena.com/api/v2/projects/1/translations"
    }
  },
  "_embedded": {
    "data": {
      "translation_1": {
        "translationId": "translation_1",
        "lang": "de_DE",
        "revision": 0,
        "translation": "This is a translated text",
        "translated": true,
        "translationPluralized": null,
        "pluralized": false,
        "projectId": 1,
        "version": "1.1.0"
        "_links": {
          "version": {
            "href": "http://my-app-arena.com/api/v2/projects/1/versions/1.0"
          }
        }
      },
      "translation_2": {
        "translationId": "translation_2",
                    .
                    .
                    .
      },
        .
        .
        .
      "translation_N": {
                    .
                    .
                    .
      }
    }
  }
}

PUT /projects/:projectId/translations/:translationId¶

Change a translation for a project specified by :projectId and :infoId

Query parameters

lang

Example request body

{
    "translation":  "new translation"
}

Example response body

{
  "status": 200,
  "data": {
    "translationId": "translation_1",
    "lang": "de_DE",
    "projectId": 1,
    "version": "1.1.0"
    "translated": true,
    "translation": "new translation",
    "translationPluralized": null,
    "pluralized": false,
    "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 /projects/:projectId/translations/:translationId¶

Deletes a translation of a project specified by :projectId and :infoId

Query parameters

lang

Example response body

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