API: Entities, Form Rendering, Interfaces and Actions - restarone/violet_rails GitHub Wiki

API & Data Pipeline Documentation

Violet Rails includes a flexible and powerful graph-based (JSON) object modelling framework called the API. The API consists of 5 main systems: API Namespace, API Resource, API Action, API Client and External API Connection

Capabilities

Define custom entities

Used for implementing flexible schemas for CRUD (create, read, update, delete) operations.

Render Forms with client-side validations

Define your form primitives in JSON with support for: file uploads, rich text, validations and recaptcha Once you define your form (backed by a model), you will see it rendered in real time

Form rendering can be performed by copying and pasting the CMS helper function in your HTML:

Perform actions

a flexible strategy for performing actions like a redirect to another page when a user submits a form, to grabbing data from an external system.

HTTP API Editor example: Discord Bot!

Here's a HTTP API Editor recipe for an action that sends a message to Discord when a form is submitted:

update: If you are running Violet Rails version 0.9.7+ you will need to rewrite your HTTP actions to not include the deprecated magic syntax. See more here: https://github.com/restarone/violet_rails/issues/836

Connect external systems to Violet Rails

To query Violet Rails from a different application, you have two options. There is a REST and GraphQL interface, both of which are available with or without authentication (if you don't use authentication you won't have write access).

Automation: Connecting and extracting data from external systems/API's

Using a combination of systems, Violet Rails is able to:

  1. Authenticate with any API
  2. Extract information from it

using a simple Ruby class defined in an External API Connection you can connect with any system using a cron or on-demand trigger. Below we have defaulted to raise error for the model, but you can define a plain old ruby class as exemplified here

Definitions

  1. API Namespace: This is the main object. Used to represent a resource, for example Users. It defines the data model along with any non-primitive attributes (file attachments, rich text etc) the model can have.
  1. API Resource: An API Namespace is the recipe for an entity. API Resource represents an instance of the entity. So a given API Namespace can have many API Resources. Eg: An API Namespace named User, will have many Users represented by a list of API Resources.
  1. API Action: is an action that that is performed when an event happens on an API Namespace or API Resource. For example, you'd want an event to be triggered when a new API Resource is created under the API Namespace User. Events can consist of: sending-- an email, a web request (to an external system), redirecting and/or serving a file (if the action is triggered in a controller).

  1. API Client: is the strategy for allowing external systems to access Violet Rails API data. It involves issuing a bearer token for a given API Namespace to register a client.

  2. External API Connection: a provider agnostic strategy for connecting with external systems. Includes web request retries with exponential backoff. Define your interface and connection rules in a plain Ruby class (PORO). See example in test for the requirements for a valid External API Connection Model definition

API resources list view

API resources of an API namespace are presented in a tabular format. Some columns are dynamically generated based on the properties of the API namespace.

For movies API namespace below, Tags and Title are dynamically-generated columns:

namespace-properties

property-columns

Rendering

There API system features a powerful renderer that debuted with the launch of Nikean's Psychedelic Storytelling platform: https://nikean.org

Overview

Blank diagram-2

The HTML Renderer is connected with the API Namespace and lets you render API Resources

View the render function used for scoping the data and rendering it

Create an API Namespace, or view an existing one and click on Rendering:

Lets dissect the snippets above:

  • {{ cms:helper api_namespace_resource_index 'story_videos', scope: { properties: { property: value } } }} : api_namespace_resource_index indicates that you will be rendering a list of API Resources. story_videos refers to the slug of the API Namespace you'd like to render. The scope object defines the scope for the API Resources that will be rendered (eg: only show published: true API Resources)
  • {{ cms:helper api_namespace_resource 'story_videos', scope: { properties: { property: value } } }} : api_namespace_resource indicates that you will be rendering a single API Resource (typically a #show page). The scope object defines the scope for the API Resources that will be rendered (eg: only show published: true API Resources)

Know which Snippet would be used for rendering data

Given an API Namespace named story_videos:

we expect the system to automatically map the Snippets used for the #index and #show views to story_videos and story_videos-show respectively:

The #show snippet (story_videos-show) exposes @api_resource object so you could write ERB markup to render it however you see fit:

The #index snippet (story_videos) exposes @api_resources array so you could write ERB markup to render a list of API Resources however you see fit:

Bring it all together

{{ cms:helper render_api_namespace_resource_index 'story_videos', scope: { properties: { published: 'true', show_in_carousels: { value: ['shorts'], option: 'PARTIAL' } } }, order: { created_at: 'DESC' }, limit: 10 }}

lets break down the above render function:

  • scope: { properties: { published: 'true', show_in_carousels: { value: ['shorts'], option: 'PARTIAL' } } }: show published API Resources only, partial match on shorts on the attribute show_in_carousels

  • order: { created_at: 'DESC' : order by created at descending

  • limit: 10: only show 10