Appirator APIs and applications are modular. Appirator modules are collections of classes and objects, event handlers and scripts related to those classes. Modules and applications can import other modules as needed to perform their functions and to reuse logic and resource class segments efficiently.
An application is a specialised module that can be started and stopped. By themselves modules cannot be started, rather their purpose is to be imported into other modules and applications. Modules hold business logic and application and API segments that can be utilised by other modules and applications so that those applications don’t need to build resources and business logic that has already been developed by someone else. These modules will either be available through external sources or through the Appirator marketplace where they can be licensed.
Where an application contains publically accessible resource classes, the application doubles as an API. However applications can be entirely private and do not need to have any API component to them. Public applications can be associated with one or more domain names so that its API endpoints are reachable over the internet. An Appirator subdomain is assigned to the application by default and developers can also assign other domains, including custom domains managed through their own registrar.
Applications, modules and all their content can be added and managed through Appirator’s APIs ([TODO - link to API documentation]). However, developers are more likely to prefer developing their applications using their favourite IDE, their favourite Git provider and by linking their Git repository to their Appirator applications directly through Git webhooks. This is more convenient method of development and provides a means of creating and coding applications and modules on their personal computers with very little direct interaction with Appirator’s services. See Module and Application Development via Git for more information.
The following are properties of all modules and consequently also applications.
Those that are configurable through the settings.yaml file are highlighted with
settings-file. They can be configured through the Appirator API or through
the Appirator admin console.
name settings-file
The name of the module. This must be unique on the account and be prefixed with one of the registered module prefixes listed on the account. Excluding the prefix, the name must begin with a-z or A-Z and can be followed by up to 59 characters a-z, A-Z, _ (underscore) or 0-9. This is a technical name for the module or application and is intended to be referenced within other modules or applications. It is case sensitive. The maximum total length of the name including the prefix is 120 characters. [TODO - verify prefixes.]
If the module or application is part of a pipeline, this value cannot be set as it is controlled through the pipeline management.
Note that if there are references to the module name in scripts that do not get updated after a change of the module name, runtime errors are likely to result.
displayName settings-file optional
The friendly name for the module or application up to 80 characters in length.
If the module or application is part of a pipeline, this value cannot be set as it is controlled through the pipeline management.
version settings-file
The version of the module or application. This must be in the format
<major>.<minor>.<build>. The build number within the version represents
the compilation number used internally within Appirator and consequently cannot
be set in a module update as it will be set automatically upon each compilation.
When setting the version the value can exclude the build number, e.g. 1.10, or
it can be set to x, e.g. 1.10.x.
pipeline read-only
This refers to the pipeline resource object when the module or application is part of a pipeline. This value cannot be set directly. It is set internally through pipeline management functions.
scriptLanguage settings-file optional
The scripting language broadly used throughout the module or application. The only supported value for this currently is JS (ECMAScript 2019) and this is default.
If the module or application is part of a pipeline, this value cannot be set as it is controlled through the pipeline management.
icon settings-file optional
The icon associated with the module or application. If this is has not been set and the module or application is part of a pipeline, the pipeline’s icon will be returned if it exists. See Artifact Management for further information.
deleteProtection settings-file optional
When enabled, the module or application cannot be deleted. This is also true when the module or application is part of a pipeline - irrespective of this flag. In this instance, the flag value is returned as true regardless.
dependencies settings-file optional
The list of module dependencies for the module or application. Each dependency permits the following properties:
name (string) - the full name of the module.license (string) - the GUID of the license associated with the module. Licenses
are managed through the Appirator marketplace.
See Marketplace
for more information about licenses and developer benefits.version (string) - the version of the module to be imported in <major>.<minor>.<build>
format. If a referenced module is not found, an error will occur during compilation.
All parts of the version can be variable, i.e.:
In general it is safe to not include the version of a dependent module as long as the module correctly honours its class migration.
properties settings-file optional
The list of property names that get used within the module or application. These properties have values of varying types, essentially the same types as that of class properties properties for the application.
These properties do not get lost if an update occurs from Git where the property values are not present in the settings.yaml file from Git. The existing values are preserved. When the properties are updated over the Appirator API, they need to be updated one by one.
validators
The list of validators in the module.
handlers
The list of event handlers in the module.
classes
The list of classes in the module.
lookups
The list of lookups in the module.
stores
The list of stores in the module.
scripts
The list of scripts in the module. These are the objects representing the scripts present in the module or application project. See Artifact Management for further information.
assets
The list of assets in the module. These are the objects representing the assets present in the module or application project. See Artifact Management for further information.
Applications are a type of module and consequently inherit all properties above. The properties below are only possible on applications. They’re not settable on modules.
domains
This is an object list, essentially of the domain names that can be used to reference the application’s API once it’s started. More than one domain can be used to reference an API, however they need to be configured ahead of time by placing the appropriate TXT record on the domain root. Once this domain record is available on the root, any subdomains are automatically allowed. If the root domain is not a pre-registered domain whose TXT record has been verified, it is still possible set the domain here, but it will not be activated until the domain registration is verified. See Domain Name Registration for more information.
Note that Appirator will assign an internal subdomain domain to all applications. This can be deleted later.
The properties that can be set per entry are:
domain (object) - a reference to the domain resource object registered under the account.subname (string) optional - the sub domain name of the root domain referred to in the domain reference. If not used, the root domain is used to reference the API.urlPrefix (string) optional - this prefixes all generated URLs with the specified base path. If the API URL is /accounts/<id>/bills and the prefix is /v1, then the external URL becomes /v1/accounts/<id>/bills.