Bosphorus web services beta announcement

Technical (archive)
1

Dear members of the openEHR community,

Having reached a point where project Bosphorus has reached a functional state, we have deployed and experimental web service under Opereffa’s current server.

The web service exposes the archetype parser functionality of Thomas Beale’s Eiffel code base with XML and JSON output. There is a simple web application at http://opereffa.chime.ucl.ac.uk/bosphorus/ which uses this web service to display XML and JSON output.

The web service is as simple as possible to use: calling http://opereffa.chime.ucl.ac.uk/bosphorus/resteasy/openehr/getarchetypeslist returns an XML list of the archetypes in repository, and calling http://opereffa.chime.ucl.ac.uk/bosphorus/resteasy/openehr/getarchetype with the archetype name as the parameter such as: http://opereffa.chime.ucl.ac.uk/bosphorus/resteasy/openehr/getarchetype?archetypeName=openEHR-EHR-CLUSTER.case_identification.v1 returns the XML output. Simply changing the URLS to http://opereffa.chime.ucl.ac.uk/bosphorus/resteasy/openehr/getarchetypeslistjson and http://opereffa.chime.ucl.ac.uk/bosphorus/resteasy/openehr/getarchetypejson allows access to JSON output.

There are known issues in the XML output, which we are fixing at the moment, but we felt that the current state of the code is capable enough to share with the community, to demonstrate the idea of turning key openEHR infrastructure functionality into web services. Thanks to functionality of the Eiffel reference implementation, this web service handles the processing of ADL 1.5 specific features and its XML output is valid according to published XML schemas (version 1.0.1). Please note that the XML or JSON output is only data, therefore its content must be placed into an AOM implementation to become a complete parser output, and we look forward to hearing from implementers, especially in the Java space to collaborate on this.

In the near future, we are going to be extending the set of services, and we would be glad to hear about your ideas for new web services in the tooling space.

The packaging and release of code will follow soon, but it will take time since Bosphorus has a fairly complicated development setup, requiring Java, C/C++ and Eiffel development setups to be configured jointly. The reference deployment of the web service is therefore the most practical way of experimenting with functionality. There are issues related to serialization of various AOM items, and it you notice errors in the XML output, please let us know so that we can fix them.

We would like to thank Thomas Beale of Ocean Informatics for providing access to his Eiffel source code and his contributions to this work, which enables us to share our work with the community.

Kind regards

Seref Arikan & Professor David Ingram,
UCL, CHIME

2

Hi Seref,

Thanks for the hard work to make this happen! I will definitely try it out.

Regarding the XML output, I think we need to find away of mapping the
content to the AOM implementation in java so we can utilize the
existing functionality in the java library.

Cheers,
Rong

3

Thank you Seref impressive work!

I’ll try the JSON services to do some javascript gui generation.

4

Hi Rong,
Actually, brute code would not be that hard to write here. I do not know if the AOM implementation is still immutable, but even then, a field by field copy to your AOM classes is not that much of a task.
A very boring one to be honest, but I’ve already written that to put protocol buffer messages into JAXB classes, this is how the web service works.

Another idea I have in mind is to wrap JAXB classes via AOM classes (getters/setters). I’ll need to write some code to get a feel for it.

Kind regards
Seref

5

Thanks Pablo,
I’m going to be updating the service today, and it is not a production service, but if you have any issues do let me know. It would be interesting to see if this can support a gui generation scenario. Please let us know how it goes!

Kind regards
Seref

6

No problem, I’m sure this could be used to GUI generation, since we already had this implemented, but we need to represent our templates with JSON too to do a 100% javascript GUI generator, now I have translate our XML templates to JSON and do a couple of tests. I’ll let you know when I have something to show.

7

for those interested in JSON, I will have a JSON outputter in the ADL 1.5 workbench in a few days. Although it is not strictly necessary, it is such a simple piece of work, I might as well do it, and provide ourselves with a JSON reference for archetypes. I will put a small rule-base in allowing some variant forms to be generated. If anyone has specific requests, let me know.

  • thomas
8

Hi!

The web service exposes the archetype parser functionality of Thomas Beale's
Eiffel code base with XML and JSON output.

Very nice work! Does this mean that it will be easy to keep it up to
date with the functionality of ADL 1.5 workbench?

for those interested in JSON, I will have a JSON outputter in the ADL 1.5
workbench in a few days

...

I will put a small rule-base in allowing some
variant forms to be generated. If anyone has specific requests, let me know.

Some REST/HTTP/URI related thoughts below:

http://opereffa.chime.ucl.ac.uk/bosphorus/resteasy/openehr/getarchetypeslist

You might want to swap at least the "resteasy" part of the URI to
something not bound to a specific product before finalizing the
interface.

http://opereffa.chime.ucl.ac.uk/bosphorus/resteasy/openehr/getarchetype?archetypeName=openEHR-EHR-CLUSTER.case_identification.v1
returns the XML output. Simply changing the URLS to

...

http://opereffa.chime.ucl.ac.uk/bosphorus/resteasy/openehr/getarchetypejson
allows access to JSON output.

Having different paths in the URIs for the same "resource" (same
archetype in this case) actually goes against some REST principles.
XML and JSON are just different "representations" of the same
"resource"

See details regarding "resource" and "representation" in the HTTP 1.1
spec http://www.w3.org/Protocols/rfc2616/rfc2616.html or Fieldings
dissertation http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm

The HTTP protocol can handle the media-type negotiation depending on
the capabilities and preferences that the client sends in the HTTP
headers. When later adding a representation with another mediatype
(e.g. YAML or protobuf) you won't need to extend the URI space (and a
lot of client code can be reused).

Of course you might want to override the HTTP negotiation in some
cases, but then I'd recommend to use a generic "media" URI query
parameter with values being media types
(http://en.wikipedia.org/wiki/Internet_media_type). If you also want
"pretty-printing" to be a selectable option (as Bosphorus seems to
provide) the resulting URI might look something like
.../getarchetype?media=application/json&archetypeName=openEHR-EHR-CLUSTER.case_identification.v1&prettyPrint=true

Having an access route with URIs like this might also be nice in the future:
.../archetype/openEHR-EHR-CLUSTER.case_identification.v1/
(Exposes the resources nicely and gives very clean URIs in listings etc)

In LiU EEE we provide URIs to RM VERSION objects (e.g. COMPOSITIONs)
like this...
http://hostname.domain.se/ehr:example-EHR-ID/129134f5-af94-4940-bea3-ad556d0efdb8::test2.eee.mi.imt.liu.se::1
and depending on what your HTTP client asks for in the HTTP headers
different representations, like XML or HTML will be returned. If a
client wants to override e.g. preset browser settings they just append
a query string like ?media=text/html

We aim to get an updated demo server online soon too and have been
focusing more on REST for the RM side of openEHR. Source code will be
published together with a paper. Perhaps we have avoided duplication
of work if you have focused on REST for AM and we mainly for RM :slight_smile:

In the near future, we are going to be extending the set of services, and we
would be glad to hear about your ideas for new web services in the tooling
space.

A web service taking a Template file (and archetypes either from
repository or uploads) as input and generating an Operational Template
(OPT) as output in JSON or XML would be very nice contribution.

There are a lot of magic output formats outlined in e.g. figure 3 of
http://www.openehr.org/svn/specification/TRUNK/publishing/architecture/am/aom1.5.pdf
that would be nice to be able produce online via http.

Again, nice work!

Best regards,
Erik Sundvall
erik.sundvall@liu.se http://www.imt.liu.se/~erisu/ Tel: +46-13-286733

9

Thanks Erik,
I have not given much thought to a REST-full design, and once I feel that the functionality is worth putting into production mode, I’ll certainly use your suggestions.
I won’t write comments inline to make it easier to follow :slight_smile:

The idea is certainly to allow everyone (including myself) have access to key ADL 1.5 related functionality, and ADL workbench offers a lot of that.
I’ve done the AOM first, since that is my #1 personal requirement. I’ve done very little RM, almost none, but I’ll be extending this to RM too. I’d really like to have a few other references for comparison. Tom already has some xml output, and he’ll modify that so that it’ll validate via published schemas (or fail :slight_smile: ) If you put your work online, that’d be another useful reference, I think having a few XML focused projects, especially in the form of web services would help a lot to collaborate on a more or less standard ITS.

I’ll talk to Tom about your suggestion regarding OPT, from my point of view, it does not sound like much work. I have actually completed only 30-40% ish of the total code I’d have to write, I am only doing Eiffel to Java with AOM. The full scope is bi directional AOM + RM. Good news is, it is not really intellectually a big challange now, since I’ve got the design working. Bad news is, it is a large piece of very boring code to write.
The Eiffel code has been under Eiffel SVN branch for a while, I’ll update that in a few days, and I’ll also upload the code of the web service and simple web app under Opereffa’s svn server. If you’re curious about how this works, you can take a look at the code.

Thanks for the kind feedback, and I look forward to working more on this.

Best Regards
Seref

10

Hi!

The web service exposes the archetype parser functionality of Thomas Beale's
Eiffel code base with XML and JSON output.

Very nice work! Does this mean that it will be easy to keep it up to
date with the functionality of ADL 1.5 workbench?

well, the workbench proper is the local GUI, so probably you mean the
compiler, RM component, and so on, which will all be progressively
exposed via Bosphorous...

A web service taking a Template file (and archetypes either from
repository or uploads) as input and generating an Operational Template
(OPT) as output in JSON or XML would be very nice contribution.

Erik, if you can put that on the tracker at
http://www.openehr.org/issues/browse/AWBPR it would help. I add
functionality based on what is in this tracker, and between the ADL 1.5
compiler and Bosphorous we will add this kind of functionality...

There are a lot of magic output formats outlined in e.g. figure 3 of
http://www.openehr.org/svn/specification/TRUNK/publishing/architecture/am/aom1.5.pdf
that would be nice to be able produce online via http.

slowly getting there :wink:

- thomas