Apps

Create custom endpoints and extend Aidbox functionality with Apps for business logic, operations, and custom resource integration.

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:

KeyTypeDescription
idstringId of the App resource
apiVersion (required)integerApp API version. Currently, the only option is 1
type (required)enumType of application. Currently, the only option is app
endpointobjectInformation about endpoint: url to redirect the request, protocol, and secret
operationsarray of operationsCustom endpoints
resourcesarray of resources in Aidbox formatDeprecated. Related resources that should be also created
subscriptionsarray of subscriptionsDeprecated subscriptions support. Consider using Aidbox topic-based subscriptions or SubsSubscriptions instead

endpoint

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

KeyTypeDescription
type (required)stringProtocol of communication. The only option now is http-rpc
url (required)stringUrl of the service to redirect a request
secretstringSecret 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:

KeyTypeDescription
methodstringOne of: GET, POST, PUT, DELETE, PATCH, OPTION
patharray of strings or objectsNew endpoint in Aidbox in array
policiesobjectAccess 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.

Last updated: