Apps | Aidbox Docs

Apps allow you to create custom endpoints in Aidbox . When a request is made to a custom endpoint, Aidbox proxies it to your application service.

An App is a standalone service that handles custom business logic. To enable this integration, you need to register the App resource in Aidbox, defining which endpoints should be proxied to your service and where to send the requests.

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>

App manifest structure

Here's the manifest structure:

Key	Type	Description
id	string	Id of the App resource
apiVersion (required)	integer	App API version. Currently, the only option is `1`
type (required)	enum	Type of application. Currently, the only option is `app`
endpoint	object	Information about endpoint: url to redirect the request, protocol, and secret
operations	array of operations	Custom endpoints
resources	array of resources in Aidbox format	Deprecated. Related resources that should be also created
subscriptions	array of subscriptions	Deprecated subscriptions support. Consider using Aidbox topic-based subscriptions or SubsSubscriptions instead
entities	array of entities	Deprecated Entities/Attributes approach to create custom resources

endpoint

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

Key	Type	Description
type (required)	string	Protocol of communication. The only option now is `http-rpc`
url (required)	string	Url of the service to redirect a request
secret	string	Secret for Basic Authorization header: `base64(id:secret)`

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:

Key	Type	Description
method	string	One of: `GET`, `POST`, `PUT,` `DELETE`, `PATCH`, `OPTION`
path	array of strings or objects	New endpoint in Aidbox in array
policies	object	Access policies to create and bound to this operation

resources

It is a deprecated option to create resources via Aidbox format.

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

It is a deprecated option to create custom resources via Entity/Attribute approach.

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

entities:
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:

entities:
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:

entities:
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.