Appirator Concepts
Overview
There are a number of core concepts in Appirator. These are shown in the following diagram within their respective containers:
Collectively, these core concepts are themselves used in building Appirator and they will also be required in creating any application or API.
Modules & Applications
Modules are the root container for everything else. Modules contain declarations for:
- Classes
- Lookups
- Validators
- Event Handlers
- Stores & Proxies
- Other module dependencies
Modules can also contain common scripts and other artifacts such as PDF and Excel templates that are used within the application.
Applications are a special type of module that contain features such as the ability to stop and start and to associate domain names.
See Applications & Modules for more information.
Classes
Classes define the schema of resource objects which are created and manipulated through API endpoints or internally through scripts. Their instances are storable, can be passed as target objects in events, can receive events, support methods, appear in scripts like native script objects and more.
A class that is marked as a public resource is automatically available as an API resource under its application domain and its resource objects will be manageable through normal RESTful operations.
Classes can have zero or more declared:
- Properties - these are present has object properties in scripts as well as over API endpoints if the class is a resource class.
- Methods - these are normal class instance methods that are accessible in scripts but are not visible externally.
- Event Handlers - these are scripts that are triggered on the reception of a specified event.
- Migrations - these are scripts that are run to upgrade or downgrade an object when it is detected that a stored resource object has a different version to the one defined within the application.
- Rules - these are a combination of scripts, validators and access policies that are run based on certain input condition.
See Classes for more information.
Lookups
Lookups are lists of constants declared within the scope of the module or application that are used to restrict the value of a class property. Class properties that are a type of lookup can only contain a value that is included in the list of entry names from the lookup.
See Lookups for more information.
Validators
Validators are used on classes and on class properties to validate values that are being assigned to a property or that the combination of values is valid.
Validators can be defined directly on the class or they can be defined globally so that they can be shared across classes.
Like classes, validators defined globally in other modules can be used on any class within the application.
See Validators for more information.
Stores & Proxies
Custom stores and proxies through which data is stored or proxied to external destinations are the same thing in Appirator. They utilise a set of CRUDS methods which are used for the setting and retrieval of data in both cases.
Stores are declared within dependent modules or within the application and are usable by any class within the application. A single class can store its properties in more than one store allowing the resource objects for the class to be derived from multiple sources.
See Stores & Proxies for more information.
Rules
Rules are a powerful feature that offers class developers the opportunity to mutate class behaviour based on contextualised input. Defined on classes or within class methods, they make it possible to deny access to class properties or entire classes if the user requesting access does not have specific permission, is not sending valid headers or any other parameter. It is possible through rules to run scripts, set up events, provide rule sensitive validation and much more.
See Rules for more information.
Events
Events are issued when any CRUD operation occurs on a resource class or object within Appirator. These events can be handled by global or class specific event handlers.
It is also possible to raise custom events and these can also be handled on their target resource objects or globally.
See Event Handlers for more information.
Event Handlers
Event handlers are configurable scripts that are triggered when a corresponding event is triggered. They can run synchronously with the trigger or asynchronously. When the script is run synchronously, it has the capability of completely interrupting the process that triggered it, resulting in a rollback of any updates that have not yet been flushed to the target. If the script is run asynchronously, this interruption doesn’t occur because the asynchronous script is guaranteed to run after the completion of the initiating process.
Event handlers can be declared on the class on which the event will be triggered or they can be declared globally within the module or application. It is possible to set up global handlers for events on resource objects that occur in other modules.
See Event Handlers for more information.
Schedules
Schedules piggyback off Events. TODO - we need to work out the scope of these. E.g. do we have a “SCHEDULE” event type?
Marketplace
The Appirator marketplace is an online shop through which third party modules and applications can be licensed. Some of these modules and applications will be free to use while others will come with a one off or yearly royalty license. All modules incur a usage cost if they consume Appirator resources during runtime.
Third party modules contain useful elements of business logic that can be connected to proprietary resource classes.
See Marketplace for more information.
File System
Every Appirator request, whether it was triggered through an HTTP request, a script or an event, is assigned a temporary file system that exists for the duration of the request. The file system contains folders that are permanent as well as folders that are ephemeral which allows files that were created during the request processing to be automatically deleted at the end of the request. It also allows files within permanent storage to be operated on with the assurance that those operations will survive across requests.
See File Systems for more information.
TODO - there’s quite a bit missing from this page