Bindaas Architecture
Bindaas owes its modular design to the features provided by OSGi (formerly known as the Open Services Gateway initiative) Framework. A typical OSGi application consists of several components or modules. Each module has its own lifecycle and can be installed, uninstalled, updated, started or stopped locally or remotely. OSGI promotes "Component Oriented Development" wherein applications are built around components; each component providing some services and features that can be used by others. It also gets around the problem of class loading issues since each component has its own classloader which does not interfere with other components. Thus it is possible for one component to use some version of a JAR and other to use an older version of the same JAR within the same application.
Some of the benefits of using OSGi are as follows:
- Easy to scale and manage.
- No class-loading mess.
- Hot deployment - Components can be installed/removed without restarting the application.
- Implicitly promotes Service-Oriented Architecture (SOA) best practices - Developers are forced to design the application in a modular SOA fashion.
There are many open-source implementations of OSGi Framework available, including Apache Felix, Karaf and Equinox to name a few. Bindaas uses Equinox which is also the technology that drives Eclipse IDE.
Apache CXF is the JAX-RS (REST) provider for Bindaas. CXF together with Jetty server provide a lightweight environment for running RESTful services.
Spring Framework is an Inversion of Control(IoC) Container used by Bindaas to manage application beans and their dependencies.
Bindaas uses the following vocabulary to describe some inherent concepts:
Bindaas APIs are organized by Projects at the very top of the hierarchy. A given Bindaas instance can have multiple Projects. Each Project is an abstraction that contains one or many Data Providers.
A Data Provider is bound to a specific project. As the name suggests it is used to describe the data you like to interact with. In most cases the data resides in a database (relational or NoSQL). Bindaas needs to know where to get the data from. Depending on the database system Bindaas requires some information such as: host, port, credentials, other miscellaneous information to establish a connection. Once a connection is establish a Data Provider gets created. Think of Data Provider as an instantiation of a JDBC connection. All query, submit or create/delete APIs are bound to a given Data Provider. Although Data Providers are generally written for a Database System, one can write Data Providers to interface with more complex systems and provide custom features.
Query API is used to query the data in the database linked to the data provider. Query API describes the query to execute, the user-supplied parameters in the query and how to format the results, in addition to other information as required by the specific implementation of the Data Provider. The query is written in the language supported by the Data Provider. For example, when a relational database is used the queries are written in SQL. The bindaas middleware itself is agnostic of any query language. We have made a conscious decision to keep bindaas middleware independent from the underlying database technology and thus are able to support multiple database systems even NoSQL. For instance, Bindaas comes with a MongoDB provider that uses its own native query language BSON (a variant of JSON) for querying.
As an API developer, the user must go through the following steps :
- Write Query - This query is pre-constructed and pre-tested to check if it yields the correct result. The user must be a domain expert and understand the underlying database schema. Bindaas expects a syntactically and semantically correct query.
- Describe the parameters in the query whose value will be provided at runtime - We call them "Bind Variables". A Bind Variable is annotated in the query using the $sign. For example, consider the following SQL statement :
SELECT * FROM PATIENT_TABLE WHERE PATIENT_ID =
Here **$PATIENT_ID$ **is a bind variable. Any name enclosing the $ sign is treated as bind variable. Bindaas looks for patterns matching this regEx to extract them and replaces it by the value supplied by the user when executing the API in the query parameter section of the URL as in
http://example.org?[query_param_list]
The Query API is executed using the following RESTful Call
HTTP GET http://server:port/services/{project}/{data_provider}/query/{query_name}?{query_param_list}
- Other information such as Output Format - Each Data Provider may provide some pre-defined formats to choose from.
Submit API can be used to submit data to the database. Again, depending on the type of Data Provider what you provide as input may change. For relational databases data in form of CSV files is supported. MongoDB accepts data in CSV or JSON format. Regardless of data format, the content must be submitted using following RESTful Call
HTTP POST http://server:port/services/{project}/{data_provider}/submit/{submit_name}
<content>
or
HTTP POST http://server:port/services/{project}/{data_provider}/submit/{submit_name}
Content-type: multipart/form-data
Update/Delete APIs, like Query API are created pretty much the same way except they cater to the update/delete queries that can edit the data. For relational databases, SQL UPDATEs and DELETEs are supported. Similarly, Mongo data source provider and the other data source providers that come with Bindaas support updates and deletes in the same way. The Update/Delete APIs are invoked as follows :
HTTP PUT http://server:port/services/{project}/{data_provider}/delete/{delete_name}
or
HTTP DELETE http://server:port/services/{project}/{data_provider}/delete/{delete_name}
Bindaas has an interesting concept of *modifier *associated with Query and Submit API. A query modifier modifies the query just before its execution. Whether to apply a modifier to a query API is optional and can be chosen at the time of creating the API. Consequently a query result modifier is used to modify the results of the query execution. A practical application of a query modifier would be one where query needs to be changed/augmented in some way depending on the authorization granted to the requester. A query result modifier could be used to perform some analytics on the data returned by the query.
For the Submit API, Bindaas provides submit payload modifier. It intercepts the payload of the Submit API before it is handed over to the underlying data provider. In the Imaging workspace images are often subject to some QA procedures before they are considered ripe for submission. Such QA procedures can be incorporated in the Submit API pipeline.
The class of Bindaas users falls into one of the following two categories:
- API Consumer - The application/user that ends up consuming the REST interfaces generated by Bindaas. The consumer does not need to know how an API is created.
- API Author / Bindaas Admin - One who creates Projects, Data Providers and Query, Submit, and Update/Delete APIs.
This section is relevant from an API author's perspective. The very first step is to create a Project and provide some description. Next, create a Data Provider by providing necessary information requested during the process. Once a Data Provider is created you can edit the properties associated with it. You can also choose to delete the Data Provider, but doing so will delete all the API associated with it.
Query, Submit, and Update/Delete APIs can be created on a Data Provider. Once created they can be executed (using the query browser) or any REST client. It is the responsibility of the Query Author to ensure that the query works. An API can be edited or even cloned to create a replica.
- Authentication
The Bindaas Middleware component secures the REST API using an "API Key" mechanism. API Key is a unique randomly generated string for each user. The API consumers must register with Bindaas using the Web Console to obtain an API Key. In order to register they must first login into the Web Console. Bindaas Web Console supports OpenID or LDAP to authenticate them. Once they login successfully for the first time they will be asked to provide a reason for the use of API. Once the request is submitted a designated Bindaas Administrator approves/denies the request and sets an expiration for the API Key.
If OpenID is used to log in users (which is deprecated as of Bindaas-3.0.0), Bindaas can be configured to send out an email notification to the user requesting access.
- Authorization
- Audit
- Writing custom Data Providers
- Writing custom Modifiers
- Query Modifier
- Query Result Modifier
- Submit Payload Modifier