API constructor (beta)

Using Aidbox API constructor you can:
define API, endpoints, handlers, and URL params schema 
specify your own middlewares (e.g. Smart on FHIR authorization middleware)
The API constructor is in beta now. Please contact us if you have questions or need help.
API constructor requires knowledge of zen language.
Usage examples:
​Sample API used in this documentation page example.
​Smart on FHIR configuration​
​ACL example​
​Multitenancy example​
Example setup
Use bb Devbox setup to start Aidbox, it contains configured API constructor example. Once Aidbox is running, open Profiles tab in the Aidbox UI. If everything is configured properly, page should contain namespace with AIDBOX_ZEN_ENTRYPOINT symbol which is mybox/box in this example. View of the symbol should show loaded routes.
Here's a notebook with the example API demo usage : 
1
https://aidbox.app/ExportedNotebook/df9ac147-daa4-4495-87b5-c4367cd441ef
Copied!
You can import it into the example bb Aidbox and run test REST requests.
API constructor definitions
Entrypoint
Define an Aidbox server definition with AIDBOX_ZEN_ENTRYPOINT env, the value must be a namespace/symbol, e.g.:
1
AIDBOX_ZEN_ENTRYPOINT=mybox/box
Copied!
The namespace with entrypoint symbol must be loaded: file containing namespace mentioned in AIDBOX_ZEN_PATHS and imported or specified directly inAIDBOX_ZEN_ENTRYPOINT env.
More info on loading namespace​
Entrypoint symbol must be tagged with aidbox/system tag. aidbox/system describes a set of services to start and configurations.
Example
1
 box
2
 {:zen/tags #{aidbox/system}
3
  :zen/desc "test server"
4
  :services {:http server}}
Copied!
Services
A service contains engine and its configuration.
Available engines:
aidbox/http - Describes http service, contains set of apis. Each api must be tagged with aidbox.rest/api.
aidbox/seed - Creates provided fixtures on start. Described here.
Example
1
 server
2
 {:zen/tags #{aidbox/service}
3
  :engine   aidbox/http
4
  :apis     #{api}}
Copied!
aidbox.rest/api
An api describes routing, route can contain operations, subroutes and other apis. Operations must be tagged with aidbox.rest/op.
:middlewares can be added to an api.
Example
1
 api
2
 {:zen/tags #{aidbox.rest/api}
3
  "multi-example" {"Patient" {:apis #{get-patient-api change-patient-api}}}}
4
 
5
 change-patient-api
6
 {:zen/tags    #{aidbox.rest/api}
7
  :middlewares [inject-tenant-mw]
8
  :POST multi-box.operations/create-patient
9
  [:id] {:PUT    multi-box.operations/update-patient
10
         :DELETE multi-box.operations/delete-patient}} 
Copied!
aidbox.rest/op
An op describes REST operation. :engine specifies what operation handler should be used for this operation. Each engine can accept own parameters
Example
1
 create-patient
2
 {:zen/tags #{aidbox.rest/op}
3
  :engine   aidbox.rest.v1/create
4
  :resource "Patient"
5
  :format   "fhir"}
Copied!
Available aidbox.rest/op-engines
Miscellaneous
aidbox.rest.v1/aidbox-action - Expects :action, passes request to existing Aidbox action. You can see list of available operations with this request:
GET /Operation?_elements=action&_result=array&_count=1000
aidbox.rest.v1/echo - expects :response in the definition, returns the response.
Regular FHIR API
Expect target resource type as :resource and :format (fhir or aidbox)
aidbox.rest.v1/search 
aidbox.rest.v1/create
aidbox.rest.v1/read
aidbox.rest.v1/update
aidbox.rest.v1/delete
aidbox.rest.v1/patch
aidbox.rest.v1/transaction
ACL FHIR API 
aidbox.rest.acl/search
aidbox.rest.acl/create
aidbox.rest.acl/read
aidbox.rest.acl/update
aidbox.rest.acl/delete
See full description and usage examples:
ACL
Middlewares
Middlewares can change incoming request before executing op. Middlewares are applied to aidbox.rest/api which contains operations or other apis. On request Aidbox routing determines what op should be executed. Before executing the op Aidbox collects all middlewares applied to the apis containing the op. Then collected middlewares are applied in sequence to the request.
A middleware should be defined with specified :engine. The :engine determines what the middleware will do. Depending on the chosen :engine middleware can accept different parameters.
Example
1
 inject-tenant-mw
2
 {:zen/tags #{aidbox.rest/middleware}
3
  :engine aidbox.rest.v1/transform-middleware
4
  :rules  {[:resource :meta :tenantId]  [:oauth/user :data :tenantId]}}
5
  
6
 change-patient-api
7
 {:zen/tags    #{aidbox.rest/api}
8
  :middlewares [inject-tenant-mw]
9
  :POST multi-box.operations/create-patient
10
  [:id] {:PUT    multi-box.operations/update-patient
11
         :DELETE multi-box.operations/delete-patient}} 
Copied!
List of available aidbox.rest/middleware-engine 
aidbox.rest.v1/match-middleware - checks if a request satisfies to some pattern. Similar to the AccessPolicy matcho engine
aidbox.rest.v1/params-middleware - adds request query-string parameters taking data from the request context
aidbox.rest.v1/transform-middleware - transforms incoming request taking data from the request context 
aidbox.rest.middlewares/transform-request-data - the same as transform-middleware but provides more complex functionality
Project with API Constructor example
Aidbox configuration with search and read on Observation resource available at GET /access/Observation and GET /access/Observation/<id>. Defined endpoints also contain a middleware injecting patient search parameter to ensure that user can only search for Observations for a specific patient.
1
{ns mybox
2
 import #{aidbox aidbox.rest aidbox.rest.v1}
3
​
4
 box
5
 {:zen/tags #{aidbox/system}
6
  :zen/desc "test server"
7
  :services {:http server}}
8
​
9
 server
10
 {:zen/tags #{aidbox/service}
11
  :engine   aidbox/http
12
  :apis     #{api}}
13
​
14
 api
15
 {:zen/tags #{aidbox.rest/api}
16
  "access"  {:apis #{access-api}}}
17
​
18
 access-api
19
 {:zen/tags #{aidbox.rest/api}
20
  "Observation" {:middlewares [inject-patient-search-parameter-mw]
21
                 :GET  obs-search-op
22
                 [:id] {:GET obs-read-op}}}
23
​
24
 obs-search-op
25
 {:zen/tags #{aidbox.rest/op}
26
  :engine   aidbox.rest.v1/search
27
  :resource "Observation"
28
  :format   "aidbox"}
29
​
30
 obs-read-op
31
 {:zen/tags #{aidbox.rest/op}
32
  :engine   aidbox.rest.v1/read
33
  :params   {:patient observation-patient-param}
34
  :resource "Observation"
35
  :format   "aidbox"}
36
​
37
 inject-patient-search-parameter-mw
38
 {:zen/tags #{aidbox.rest/middleware}
39
  :engine aidbox.rest.v1/params-middleware
40
  :params {:patient {:path     [:user :data :pid]
41
                     :required true}}}
42
​
43
 observation-patient-param
44
 {:zen/tags   #{aidbox.rest/param}
45
  :engine     aidbox.rest.v1/param
46
  :search-by  aidbox.rest.v1/search-by-knife
47
  :name       "patient"
48
  :expression [["subject" "id"]]}}
Copied!