Apps

You can extend Aidbox with custom Apps. The app can:

• define custom resources,
• define custom endpoints,
• subscribe to hooks or subscriptions.

The app is a standalone service that will work with Aidbox to implement your specific app. The app should be registered in Aidbox.
Aidbox SDKs support using Apps:

Example of App resource

To define the App, we should provide the app manifest.

PUT /App/myorg.myapp

resourceType: App
id: myorg.myapp
apiVersion: 1
type: app
endpoint:
   url: https://my.service.com:8888
   type: http-rpc
   secret: <your-sercret>
operations: <Operations-definitions>
resources: <resources-to-be-created>

App manifest structure

Here's the manifest structure:

endpoint

In the endpoint section, you describe how Aidbox will communicate with your service:

operations

In the operation section, you define Custom REST operations as a map <operation-id>: <operation-definition> and access policy (which will be bound to this operation):

operations:
  daily-patient-report:
    method: GET
    # GET /Patient/$daily-report/2024-01-01
    # GET /Patient/$daily-report/2024-01-02
    path: ['Patient', '$daily-report', { name: 'date'} ]
  register-user:
    method: POST
    path: [ 'User', '$register' ]
    policies: 
      register-user: {  engine: allow }

Parameters:

resources

In the resources section, you can provide other resources for Aidbox in the form {resourceType: {id: resource}} using Aidbox format:

resourceType: App
resources:
  # resource type
  AccessPolicy:
    # resource id
    public-policy:
      # resource body
      engine: allow
      link:
        - {id: 'opname', resourceType: 'Operation'}

In this example, the AccessPolicy resource will be created as well as the App resource.

entities

In the entities section of the App manifest, you can extend existing resources, define custom profiles, or hook into the lifecycle:

Patient: # existing resource type
  attrs:
     # here we define extension `race` for patient
     race: { extensionUrl: 'https://myapp/race', type: 'code' }
  hooks: # resource life cycle hooks
    before_create: # map of hooks <hook-id>: { config-map }
       notify_on_patient: { emails: ['admin@hs.io'] }

As well as define custom resources:

User: # custom resource type
  attrs:
     email:    { type: 'email', isRequired: true }
     password: { type: 'password' }
     active:   { type: 'boolean' }
     patient:  { type: 'Reference', refers: ['Patient'] }
     settings:  
        attrs:
           theme: { type: 'string', enum: ['black', 'white'] }
  hooks:
     before_create:
        check_ldap: {}
     after_create:
        save_to_third_paty: {}
  profiles:
     user-uniq-email: 
       type: sql 
       query: SELECT true FROM "User" WHERE resource->>'email' == {{ .email }}
       message: Email is already taken

In the entities section, resources are defined in the format <resourceType> : <structure> :

entities:
  Patient: <structure>
  User: <structure>
  Payment: <structure>

Resource structure is defined by attrs keyword:

User:
  attrs:
    email: <element-definition>
    password: <element-definition>
  profiles: <profiles-definition>
  hooks: <hooks-definition>

At the root of resource definition, you can also define hooks and profiles for this resource.