About shims
Integrating data from disparate streams can be an daunting task. If you were to start from scratch, you'd need to learn the custom API of each data provider, write a client to pull data from their data streams, come up with the data format to use, and map each response to that common data format. That takes a lot of time, and keeping up with new APIs and changes to those APIs becomes a maintenance nightmare. There's a better way.
What are shims?
A shim is an adapter between an Open mHealth API and the API of a third-party data provider. Our API offers simple RESTful operations to retrieve data in an Open mHealth compliant data format. To produce that data, a shim calls one or more operations on the custom API of the data provider. The data the shim receives from those calls is translated into a compliant data format and decorated with provenance information before being returned from the Open mHealth API.What are the benefits of shims?
An application uses shims to integrate with one or more third-party APIs. Since the application only makes calls to a common API, its business logic is decoupled from the custom APIs. A developer does not need to learn the data formats, authentication mechanisms, and nuances of each custom API in order to access data from it. This makes it much easier to work with data coming from different places, and gets you up and running very quickly.Why are they called “shims”?
Open mHealth wants data providers to natively provide a common API that produces meaningful data. That’s a long term goal, and shims are the stopgap. They let your application integrate with data providers using a common API they have yet to support. Once the common API is implemented by a data provider, the shim for that provider is no longer used.How do shims authenticate?
Different third-party APIs use different authentication mechanisms. OAuth 2.0 is the most common, but OAuth 1.0a is also popular, and some data providers roll their own authentication mechanism.How do I use a shim?
A shim is run within a shim server. The shim server offers the common API, and delegates requests to the correct shim. It’s analogous to a normalizer in an event-driven architecture. Read the shim server installation instructions and API documentation on GitHub.Why are shims written in Java?
We’ve written the shims in Java because it’s what we’re good at and because it’s a mainstream language, making it more easy to understand. A shim can be implemented in any language, of course, but if you use the Java shim server, you’re currently limited to Java, Groovy, and Scala. We’re currently discussing turning shims into microservices that can be implemented in any language.What’s in a shim?
A shim typically contains- A mapper and corresponding unit tests for each measure being mapped.
- A controller that contains authentication logic and delegates to mappers.
- Access to a data store that contains OAuth client credentials and access tokens.