General Concepts
Elements preserves several consistent concepts across every API. Throughout this manual, we will use several paradigms which govern how Elements models data within the system. The general concepts are guidelines around with the API functions.
Data Models
Among the data models present within Elements, several will contian the following properties. In all cases the properties represent the same consistent concept.
- id is always the system-assigned unique ID of the particular.
- name represents a unique system-readable reference to the particular object.
- metadata represents user editable metadata which Elements will store with each object for more information on effective using metadata.
- tags are a list or set of words used to categorize and filter content.
- displayName a display name used to refer to the object within the UI and potentially the final page or application.
- timestamp represents a time stamp or similar property
Id Property
id always refers to the databased assigned unique ID of a particular object. Due to the server authoritative nature of Elements, the unique ID is always assigned server side and will always be the absolute unique identifier of a particular object. In all cases, the server side generates the identifier.
Tips on using id Effectively
- Always treat IDs as opaque values. For example:
- Do not assume any particular format of the ID. At the time of this writing, all server IDs are hex strings. There is not a strict requirement for future editions of Elements.
- Some IDs may contain encoded data. Unless specifically documented, do not assume that any IDs will always follow the same encoding format.
- IDs are always handled as strings in request and response objects.
- The server will always generate IDs.
- Some APIs will accept either an ID or a name for certain operations. Unless otherwise specified, always pass the ID.
Name Property
name represents a unique system-readable reference to the particular object. The name assigned to any object is always intended to be an alternative unique id for the object. Understanding this is crucial for integrating backend scripts and client-side application code. Unless otherwise specified, the name can be used as a programmatically unique id in all parts of the code. Additionally, two unrelated items may share a name. For example an Item and a Mission may share a name, however two Items may not share the same name. Names are case-sensitive and must be an alphanumeric string with no spaces.
Tips on Using Names Effectively
- Use a consistent convention. For example, all lowercase with underscore separation. If, for example, you wish to model a Paper Hat as an item. A good name would simply be
paper_hat
. All code may not refer to this when fetching Paper Hat Items from the database. - Use the name wherever possible, unless there is a specific need to use the database id. This ensures that scripting engine code can refer to the specific object even if the object has been deleted and recreated, such as migration between two separate instances of Elements.
- Give all objects a clear name that is obvious to the reader. This will avoid problems with ambiguity when designing your system.
Metadata Property
metadata represents user editable metadata which Elements will store with each item. This data may be used for any purpose and will not be modified or touched by Elements in any way. Depending on circumstance, this may or may not be editable by regular users. At the time of this writing, it is not possible to index by metadata. At the time of this writing, all metata must be written in a server-authoritative way. In other words, only superusers and scripts running in the backend may modify metadata. This may be subject to future enhancements. In all cases it is a multi-layered key-value object. The admin panel allows for simple editing of metadata as key-value strings, as well as editing as inline JSON metadata. Some objects work with metadata schema, and full support for metadata schema is actively under development for all remaining system types.
Tips for Using Metadata Effectively
- Metadata is not indexed, so you should not make objects searchable via metadata.
- It is intended to add custom fields to objects which do not have sufficient support for data on its own. For example, when attached to a Profile, the metadata may represent the current exp, level, or status of equipment slots.
- In general, the metadata should not include secure or sensitive information.
Tags Property
For example, items tagged with "armor" and "head" may represent helmets equipped to a character in a game. Tags are indexed for optimal querying from the database and should be used to quickly separate content when making API calls. Effectively using tags enables developers to quickly filter items as the tags are indexed and all APIs supporting tags support the querying of the tags.
Tips for Using Tags Properly
- When querying tags, they are always all-inclusive. For example if
paper_hat
has tagsarmor
andhead
, will show up in searches for botharmor
andhead
, onlyarmor
, or onlyhead
. It will never appear ifweapon
is specified in the search terms. - There is no specific limit on tags, but too many tags may run up against database limitations. However, practically speaking, Elements will allow far more tags than what is necessary for a majority of use cases.
Display Name Property
The display name is simply a name to use when displaying the object in the admin console, or potentially to end users. It is not indexed, and should never be used to make data decisions or in programatic code. It's simply there for human readability and visual reference.
Timestamp Property
Elements represents timestamps and dates using the same notation used by the Java Virtual Machine. Timestamps are a 64-bit integer counting the number of milliseconds since the Unix Epoch (January 1, 1970). For more information see System.currentTimeMillis()