I started using OpenAPI a few months ago, but I'm finding multiple caveats while generating documentation. This of course leads me to believe that I must be doing something wrong.
So, I usually begin always by creating the schemes for the multiple resources of my API, I then place a reference to the schemes on the request bodies for each respective endpoint. However I find that this approach makes generated documentation confusing, adding for example an id parameter on the request body of a user create operation when it's clearly not supposed to be there (Of course the user is being created at this point, so there isn't even an ID in the first place, and why would an ID be part of the request body?).
I ended up just making multiple schemes for a single data model, I would choose which one I used based on the operation (E.g. Creating vs Displaying), this way I could generate documentation more accurately. This helps me avoid situations like displaying relations that are generated post-creation on a create operation. (I know I'm probably not phrasing all this correctly but just bear with me).
In a nutshell, I'll end up with approximately 3 or 4 schemes per data model. For the User model I'll have for example User, UserNew, UserSubscriptions, UserAll. All schemes represent the same resource, they just differ in the data that they display.
Again, I feel like this is not the way that OpenAPI is meant to be used. So I hoped that maybe someone here that has more experience with this could guide me on the right path! Thank you.
Is it Possible to convert a complete CCDA xml to a FHIR based xml? I would like to convert an complete CCDA xml to a FHIR compatible XML through Mirthconnect interface.
I like to have sample messages that shows how a complete CCDA is been transformed to FHIR based XML, I googled and ended up with no answers. It would be great if you guys help me.
Strictly speaking, C-CDA is consolidated CDA. It is an IG - Implementation Guide.
In simple terms, there are various IG for generating a CDA document HITSP/C83 for one is an example and there are several others. The main problem with all these seperate IG is that they are not uniform. C-CDA was created to bring uniformity of data. This presentation here is a good place to start. Basically, it says you got to have at least 4 mandatory section in your CCD, and rest optional sections. It entirely depends on your use case.
Secondly, You need to download a copy of a valid C-CDA file from this site. Let's take inpatient summary document.
So that would be your target document, and consider it as a template.
Third, You got to tell your engineering team or if you are the developer yourself, then you need to build logic to extract and place information into that template. This is an iterative process, and everytime you need to validate your developed document, against the validator (site given above).
Until and unless the validator says 0 errors present, your document is not ready.
So, There does not exist a ready made code or logic that you can just plug and play and start developing C-CDA documents.
My work routinely requires us to deliver documentation to our customer and other parts of the business. These documents are in the Microsoft Word format, and use a template stored on our servers. Our colleagues and the customer occasionally comment that the documents take a long time to open, as each one tries to connect to our server to locate the template, and either succeeds or fails and times out.
Is it possible to keep each document in their current format (i.e. with the template applied), but not require it to go looking for the template every time it is opened? Mostly for the customer who cannot access our servers for the template. Ideally, we do not want to deliver the template with the documentation.
No, it's not possible to stop the document looking for the template. This is a bigger problem with some versions of Word than with others. But best would be to use a tool to link the document to Normal.dotm (or Normal.dot if this is pre-2007) before sending it out. The tool could generate a Document Variable to store the path to the original template so that another tool (or the same one) can re-attach the template when/if the document comes back.
If I include a password protected PDF file in my app, and upload to iTunes, do I need to say it contains encryption?
The app opens and displays the contents of the PDF file automatically, so the user never has to enter the password.
EDIT:
According to this pdf from the U.S. Bureau of Industry & Security: http://www.bis.doc.gov/encryption/flowchart1.pdf
And this related page:
http://www.bis.doc.gov/encryption/question1.htm
The product does contain encryption but falls under the exception rule:
Is the encryption functionality limited to intellectual property or copyright protection functions? YES
I'm guessing the way to answer in iTunes is:
Is your product designed to use cryptography or does it contain or incorporate cryptography? YES
Does your product qualify for any of the exemptions provided in Category 5 part 2? YES
Yes, since password protected PDF files are encrypted and your including it in your app.
In some way... i thing... yes:P
but i don't know the politics of itunes etc...
i think that application resources can be encrypted, without warning the public becouse you sell the app not the resources by it self
The short answer is yes, it uses encryption and is considered an encryption application.
The slightly longer answer is that under Note 4 to 15 CFR part 774, Supplement 1, category 5, part 2, the use of encryption solely for copyright protection does not require classification or special licensing.
See http://www.bis.doc.gov/encryption/question6sub_2.htm
However, a complete answer would also include how the source code and related encryption technology are handled. Source code is often subject to more restrictive treatment than the compiled and/or mass marketed app.
You can also call the Bureau of Industry and Security help line at 202-482-0707. There's also a web page with Q's & A's at www.bis.doc.gov/encryption
For a website I am working on defining a RESTful API. I believe I got it (mostly) correct using proper resource URIs and proper use of GET/POST/UPDATE/DELETE.
However there is one point where I can't quite figure out what the proper way to do it "in" REST would be - comparison of lists.
Let's say I have a bookstore and a customer can have a wishlist. The wishlist consists of books (their full Book record, i.e. name, synopsis, etc) and a full copy of the list exists on the client. What would be a good way to design the RESTful API to allow a client to query the correctness of its local wishlist (i.e. get to know what books have been added/removed on the wishlist on the server side)?
One option would be to just download the full wishlist from the server and compare it locally. However this is quite a large amount of data (due to the embedded content) and this is a mobile client with a low-bandwidth connection, so this would cause a lot of problems.
Another option would be to download not the whole wishlist (i.e. not including book infos) but only a list of the books' identifiers. This would be not much data (compared to the previous option) and the client could compare the lists locally. However to get the full book record for newly added books, a REST call would have to be made for every single new book. Again, as this is a mobile client with bad network connectivity, this could be problematic.
A third option and my favorite, would be that the client sends its list of identifiers to the server and the server compares it to the wishlist and returns what books were removed and the data for books that were added. This would mean a single roundtrip and only the necessary amount of data. As the wishlist size is estimated to be less than 100 entries, sending just the IDs would be a minimal amount of data (~0.5kb). However I don't know what kind of call would be appropriate - it can't be GET as we are sending data (and putting it all in the URL does not feel right), it can't be POST/UPDATE as we do not change anything on the server. Obviously it's not DELETE either.
How would you implement this third option?
Side-question: how would you solve this problem (i.e. why is option 3 stupid or what better, simple solutions may there be)?
Thank you.
P.S.: A fourth option would be to implement a more sophisticated protocol where the server keeps track of changes to the list (additions/deletes) and the client can e.g. query for changes based on a version identifier or simply a timestamp. However I like the third option better as implementation-wise it is much more simpler and less error-prone on both client and server.
There is nothing in HTTP that says that POST must update the server. People seem to forget the following line in RFC2616 regarding one use of POST:
Providing a block of data, such as the result of submitting a
form, to a data-handling process;
There is nothing wrong with taking your client side wishlist and POSTing to a resource whose sole purpose is to return a set of differences.
POST /Bookstore/WishlistComparisonEngine
The whole concept behind REST is that you leverage the power of the underlying HTTP protocol.
In this case there are two HTTP headers that can help you find out if the list on your mobile device is stale. An added benefit is that the client on your mobile device probably supports these headers natively, which means you won't have to add any client side code to implement them!
If-Modified-Since: check to see if the server's copy has been updated since your client first retrieved it
Etag: check to see if a unique identifier for your client's local copy matches that which is on the server. An easy way to generate the unique string required for ETags on your server is to just hash the service's text output using MD5.
You might try reading Mark Nottingham's excellent HTTP caching tutorial for information on how these headers work.
If you are using Rails 2.2 or greater, there is built in support for these headers.
Django 1.1 supports conditional view processing.
And this MIX video shows how to implement with ASP.Net MVC.
I think the key problems here are the definitions of Book and Wishlist, and where the authoritative copies of Wishlists are kept.
I'd attack the problem this way. First you have Books, which are keyed by ISBN number and have all the metadata describing the book (title, authors, description, publication date, pages, etc.) Then you have Wishlists, which are merely lists of ISBN numbers. You'll also have Customer and other resources.
You could name Book resources something like:
/book/{isbn}
and Wishlist resources:
/customer/{customer}/wishlist
assuming you have one wishlist per customer.
The authoritative Wishlists are on the server, and the client has a local cached copy. Likewise the authoritative Books are on the server, and the client has cached copies.
The Book representation could be, say, an XML document with the metadata. The Wishlist representation would be a list of Book resource names (and perhaps snippets of metadata). The Atom and RSS formats seem good fits for Wishlist representations.
So your client-server synchronization would go like this:
GET /customer/{customer}/wishlist
for ( each Book resource name /book/{isbn} in the wishlist )
GET /book/{isbn}
This is fully RESTful, and lets the client later on do PUT (to update a Wishlist) and DELETE (to delete it).
This synchronization would be pretty efficient on a wired connection, but since you're on a mobile you need to be more careful. As #marshally points out, HTTP 1.1 has a lot of optimization features. Do read that HTTP caching tutorial, and be sure to have your web server properly set Expires headers, ETags, etc. Then make sure the client has an HTTP cache. If your app were browser-based, you could leverage the browser cache. If you're rolling your own app, and can't find a caching library to use, you can write a really basic HTTP 1.1 cache that stores the returned representations in a database or in the file system. The cache entries would be indexed by resource names, and hold the expiration dates, entity tag numbers, etc. This cache might take a couple days or a week or two to write, but it is a general solution to your synchronization problems.
You can also consider using GZIP compression on the responses, as this cuts down the sizes by maybe 60%. All major browsers and servers support it, and there are client libraries you can use if your programming language doesn't already (Java has GzipInputStream, for instance).
If I strip out the domain-specific details from your question, here's what I get:
In your RESTful client-server application, the client stores a local copy of a large resource. Periodically, the client needs to check with the server to determine whether its copy of the resource is up-to-date.
marshally's suggestion is to use HTTP caching, which IMO is a good approach provided it can be done within your app's constraints (e.g., authentication system).
The downside is that if the resource is stale in any way, you'll be downloading the entire list, which sounds like it's not feasible in your situation.
Instead, how about re-evaluating the need to keep a local copy of the Wishlist in the first place:
How is your client currently using the local Wishlist?
If you had to, how would you replace the local copy with data fetched from the server?
What have you done to minimize your client's data requirements when building its Wishlist view(s) and executing business logic?
Your third alternative sounds nice, but I agree that it doesn't feel to RESTfull ...
Here's another suggestion that may or may not work: If you keep a version history of of your list, you could ask for updates since a specific version. This feels more like something that can be a GET operation. The version identifiers could either be simple version numbers (like in e.g. svn), or if you want to support branching or other non-linear history they could be some kind of checksums (like in e.g. monotone).
Disclaimer: I'm not an expert on REST philosophy or implementation by any means.
Edit: Did you ad that PS after I loaded the question? Or did I simply not read your question all the way through before writing an answer? Sorry. I still think the versioning might be a good idea, though.