So I had a look on the demo server compose file it seems like we dont have a volume attached to the demo server mysql which means basically in everystartup We start with brand new database with out the previous data that was created by users.
Am not sure the reason for this is there any specific reason @burke?
This is by design. The demo server is for demonstration. People play with it and the data are reset daily.
@ayesh @burke I was looking throught this post here and got something for fiddling with the swagger based documentation here. is it still relevant for our project ?
Hi @saurabh
No I think it was back in 2015 before generating the swagger docs with try out options.
Correct. The auto-generation of Swagger documentation is a cool idea but has two problems: (1) generating at runtime means you have to wait for documentation to be generated every time you reference it and (2) there are a lot of gaps in the auto-generated documentation (many properties labeled as a “string” with no description or examples and a lack of any high level documentation to tell you when/why to use resources, tips for best practices, etc.).
Ideally, we’d use an auto-generation approach like this at build time to automate parts of our static documentation (e.g., “try it out” examples) and to highlight where our manual documentation might be misaligned or out of date with changes in the code.
@burke @ayesh are there any significant differences between when should we use the term sub-resouces and when should we use the term metadata-types. here I read that we use the term metadata-types for things we describe as sub-resources in our RestAPI docs ?
Subresource is a technical term for properties of a resources that are themselves surfaced as separate resources. The term “subresource” may be useful for people developing the the REST API, but I think the term is confusing to people consuming the API and would prefer that we not use it so much in our documentation.
Metadata could be thought of as “data about data” or “supporting data” or “system data”. Examples may help:
| Data | Metadata |
|---|---|
| Bob is right-handed. | A person can be right-handed, left-handed, or ambidextrous. |
| Eve’s temperature is 37°C | Temperature is measured in centigrade and can be between 25 & 43 |
| Wyclif’s encounter in Clinic A | The hospital has clinics: Clinic A, Clinic B, and Clinic C |
Trying to say it another way, data are information about a patient and metadata are information about the data we collect. The supporting information of encounter types, concepts, locations, etc. are types of metadata. The information we collect about patients (observations, encounters, notes, etc.) are data. When you are looking at the data model, you’ll see data can be deleted (voided); metadata cannot be deleted once used (if you recorded encounters at a location last week, deleting the location would invalidate all those data), but metadata can be retired to keep it from being used going forward (when a concept, location, or other metadata are retired, it means it should no longer be used but does not invalidate any data previously collected using those metadata).
@ayesh @burke here is the compiled file for the survey responses.
but they arent so easy to visualize so I am attaching screenshots as well.
Hi @saurabh ,we also found these links might be helpful to you during this phase of the program cc @jennifer https://wiki.openmrs.org/display/RES/OpenMRS+Community 8:11
Interesting. So, this seems to confirm my assumption that people like concise, descriptive documentation (like GitHub’s docs) and would like to see it more comprehensive (covering more resources and including modules that extend our REST API).
I’m still advocating this approach:
While I think the ideal solution would be most of the static documentation (except some manually managed text for intro/overview/auth/contributing) generated automatically by a Swagger-like tool grepping our code (including modules) with gaps filled by well-written annotations/Javadocs in the code, I don’t think figuring out the technical solution is a good use of GSoD. We need decent descriptions, examples, etc. whether they are written manually into a GitHub repo or placed in the code… we can always copy & paste them elsewhere in the future if needed.
@ayesh I have made few changes to the project timeline (In the project proposal) as @burke suggested,
So I will be working on resources ie patient,encounter,visit and obs for making them better and in parallel, I would be fixing and patching other parts of the documentation with examples and additions. when we would be ready with these 4 resources we can have a small review of these resources and then move forward with expanding this standard to other resources as well.
@ayesh I would edit the flow if you have some changes to suggest 
!!
@ayesh @burke can I rely on this data model doc to annotate the current resource attributes with required tags?
Hi @burke
Yes I like that approach.
So what are the first 3 resources we are going to document.
I believe it’s best to get developers input for the documentation. Will it work if we go with another survey to identify missing points. Or direct messages may be a new talk thread where all dev people can give their opinion would work ?
There are a few ways to approach this…
Take 2-3 resources that have high value & test different aspects of our documentation needs. For example:
Search Talk for examples of people struggling with the REST API like here, here, and here and focus on those resources.
Find a couple people who are familiar with OpenMRS and it’s data model, but who have never used the REST API, and record sessions of them trying to do some specific operations using the REST API (e.g., find a patient, register a patient, create a new concept for a fake lab test, record an encounter for the registered patient containing a result for the fake lab test).
With a & b, while you could requests the community to review & comment, but we’d want to enlist at least one n00b, one /dev/2, and one expert to review the documentation and make suggestions. It would probably be easiest for them to schedule a 30- or 60-minute call where they share their screen and read through the documentation and give you feedback. An alternative (or additional option) would be to convince/urge some developers who are doing active development to try using the documentation and then give you feedback on their experience.
With c, the person’s successes & challenges trying to learn & use the REST API would point out its strengths and weaknesses.
@ayesh @burke I am starting working on these resources, as you mentioned and will get back for feedback and suggestions.
what should we use for adding JavaScript examples jquery based vs fetch based I dont know which one would be better . I will update the getting started guide accordingly !!
should we add responses for all restAPI calls that we have or some specific ones ?
Hi @saurabh
Shall we first finish Java Examples?. Adding examples in the current form is easy. But we have to focus on what @burke mentioned here.
yes Sure @ayesh I was going to add all the examples for the resources burke mentioned so that they are complete in that aspect also for other resources I am not currently starting javascript examples
