How can complex obs (e.g. images) be created through the REST API?

[Jamie Neil]

Hi,

I'm trying to create an obs via the REST API which uses a complex concept (happens to be JSON format, but could be any structured text format, image or other binary blob), but looking through the code there seems to be no support for handling them. Does anyone have any examples of modules which do handle the injection of these kinds of structured data into OpenMRS?

I did already ask this question on the talk space, but didn't receive any responses so I assume it was the wrong forum.

Regards,

Jamie Neil

[Darius Jazayeri]

Hi Jamie,

The REST API currently does not support this.

We're looking for someone to pick up the issue for this: https://issues.openmrs.org/browse/RESTWS-297 :-)

The quickest path towards this would be to write a custom module that exposes an endpoint at some URL with some custom way to create/edit complex obs, and writes directly to the Java API.

-Darius

--
OpenMRS Developers: http://om.rs/dev
Post: d...@openmrs.org | Unsubscribe: dev+uns...@openmrs.org
Manage your OpenMRS subscriptions: http://om.rs/id
 
Visit OpenMRS Talk at http://om.rs/talk for chat and discussions!

[Lluis Martinez]

Would be acceptable to send the contents encoded as Base64 ? Perhaps not the best solution, but easy to implement.

http://stackoverflow.com/questions/4083702/posting-a-file-and-data-to-restful-webservice-as-json

To unsubscribe from this group and stop receiving emails from it, send an email to dev+uns...@openmrs.org.

[Jamie Neil]

Hi Darius,

I figured as much, just wondered if anyone had already done some work in another module that had to deal with the problem.

Creating an api module just to handle complex obs sounds like the easiest approach for now.

Thanks,

Jamie

[Jamie Neil]

Yes, for binary data like images I was thinking that Base64 would be the obvious choice for encoding, and I've done this before for a previous REST API and it seemed to work pretty well. If there's a better way of doing it then I'd be interested to hear.

[Burke Mamlin]

By design, the complex obs handler is responsible for working with its complex obs values, including both how to store & retrieve those values as well as how the values should be represented for different views.  To that end, a REST representation of a complex obs value should be a new view – e.g., "JSON_VIEW".

The API, including the REST API, should not be deciding on how complex obs values should be represented; rather, it should ask the handler for the needed representation.  Base64 might make sense for an image being sent over JSON, but would be competely inappropriate if the complex value is a short plain text string like a location name or user's system ID.

Cheers,

-Burke

[Jamie Neil]

I wasn't suggesting Base64 be used for _all_ complex obs values, just images and maybe other binary formats. Delegating the decision to the handers sounds like a good approach to me. Is it possible to add new views to existing complex obs datatypes without modifying the core?

[Burke Mamlin]

The views are just strings.  Common views are in included as constants in core so handlers can reference those constants and to serve as a naming/style convention, but a handler can report supported views and report whether or not a specific view is supported through the ComplexObsHander interface, so you can introduce a new view without changing core.

In the REST module, when it needs to render a complex obs value, it could ask the handler if it supports JSON_VIEW.  If the answer is no, then either fail or, better yet, send a URI to the raw view.  If the answer is yes, then ask the handler for the complex value using JSON_VIEW.

The JSON_VIEW = "JSON_VIEW" constant could start out (for now) as a constant within the RESTWS module, but it would be nice to create a PR to add this constant to ComplexObsHandler.java, so the constant could eventually be removed from the RESTWS module.

Cheers,

-Burke

[Lluis Martinez]

Complex obs are sent to the core API as a stream, this stream is opened in the controller from the file uploaded (standard http upload). The stream is serialized to the file system (in a particular location). When viewed, Openmrs opens the file and writes its contents to the response. If it's a known mime type the browser knows and displays it (either in the browser or with an application). 

The REST controller could do exactly the same, get the data (base64 encoded, plain text) open a stream (binary or string) and invoke the current API. And the other way around.

Complex obs "handlers" are still a mistery to me.

Cheers

[Saptarshi Purkayastha]

The problem with using Base64 strings for the "value" field is that you will also need to add a mimeType field, which is missing at the moment in ObsResource. I know in 1.12 the ComplexObsHandler added the mimeType. So that can be used by the RESTWS module, but then this feature will only work with newer versions of OpenMRS.

We can offcourse send a BSON or Binary JSON, but there the tooling for clients is not widespread. I would recommend that we provide a link for complex obs in the value field in the ObsResource and that link will provide just the value of the ComplexObs with the correct Content Type: headers in the GET... Doing a POST is slightly more complicated. One would have to post value in a different call with the correct mimeType for ComplexObs...

So, although that ticket mentions it should be handled like ComplexNumeric, its not that straightforward. Unless, we agree that this feature only works on platform 1.12 and then we add a mimeType field when its a complex obs.

---
Regards,
Saptarshi PURKAYASTHA

Visiting assistant professor

Department of BioHealth Informatics, IUPUI

[Namrata Nehete]

Hi all,

I am currently working on RESTWS-297. I see, the core API makes the assumption that ImageHandler is always WebImageHandler. I feel this assumption is incorrect because this changes RAW_VIEW (from ImageHandler) to URL_VIEW or HTML_VIEW. This code is good for web browsers, but for REST clients forces another GET call. POST will hence need another resource.

So I suggest that the webservices.rest API uses the DEFAULT_VIEW (ImageHandler for images, TextHandler for text, BinaryDataHandler for binary data etc.) instead of the WebxxxHandler. Is that acceptable?

---
Regards,
Namrata Nehete.

[Saptarshi Purkayastha]

Clearer demarcation between the service layer and the view layer is much needed. Client side services need to live on the view layer. I know we are trying to be more opinionated about the EMR and distros, but that can be achieved through generic services that allow clients to use those services to store their settings, instead of us building client-side services on the server-side.

To answer this specific question, I feel that instead of creating our custom views (RAW, URL, HTML etc.), we should use HTTP headers, for representations. For the RESTWS module this is nicely done through the Accept header, but for only two types (application/json and application/xml) is really supported. An HTML view will be nice to have and probably good for documentation, but is another story. If the client asked for JSON, they are explicitly expecting (generally speaking UTF-8 encoded, unless specified) characters that is a valid JSON. Like Lluis said, and many people do, binary content can be GET as Base64 string, but with its corresponding correct mimeType. For a POST, the value field with its Base64 string is fine, but we also need to deal with its mimetype. 

I feel Base64 encoding on the client side is troublesome and particularly that we want to support low-resource settings. I suggest that the "value" field of the obs resource should be a URL pointing to a /complexobs/{uuid} resource that supports GET binary/text data and POST with Content-Type: multipart/form-data and Content-disposition. In our ComplexObsServlet, we assume a .jpg type which is not correct. The way many other projects/web servers are doing this is using the Apache Tika project. I recommend that we use Apache Tika for content detection and not have the user set mimeType at all.

Burke, why is Handler a server-side consideration? Probably a client-side thing for our web application. Is it because you expect that multiple images (in a complex obs) can be converted into a video and that view can be requested? Can you give some use-cases where supportedViews is a server-side problem to be solved.

---
Regards,
Saptarshi PURKAYASTHA

Visiting assistant professor

Department of BioHealth Informatics, IUPUI

[Namrata Nehete]

Any views? Please reply. I can also be on a design call to put my points forward.

---
Regards,
Namrata Nehete.

[Wyclif Luyima]

Hi Nehete,

The REST API currently doesn't have support for processing complex Obs but we have had discussions about it on the dev list in the past but i don't think anything has been implemented but we should in future versions of the module.

Wyclif

Wyclif Luyima
Regenstrief Institute Inc.

Confidentiality Notice: The contents of this message and any files transmitted with it may contain confidential and/or privileged information and are intended solely for the use of the named addressee(s). Additionally, the information contained herein may have been disclosed to you from medical records with confidentiality protected by federal and state laws. Federal regulations and State laws prohibit you from making further disclosure of such information without the specific written consent of the person to whom the information pertains or as otherwise permitted by such regulations. A general authorization for the release of medical or other information is not sufficient for this purpose.

If you have received this message in error, please notify the sender by return e-mail and delete the original message. Any retention, disclosure, copying, distribution or use of this information by anyone other than the intended recipient is strictly prohibited.