On today’s design call, we discussed AF-46, and we came up with a proposed convention. Opinions welcome!
We (@burke, @darius, with @wyclif dissenting) propose that modules should generally publish their REST resources at the top level, alongside the core resource. E.g. the appframework module would create two resources “app” and “extension” alongside the core ones like “concept” and “patient”.
We think it will be more intuitive for REST consumers who are not in the weeds of OpenMRS to see a URI like “app”, rather than “appframework/app”. And Burke further thinks that it’s better to manage any potential name conflicts socially and by conversation, rather than enforcing namespacing in our standard conventions.
(Personally I’d point out that modules are still allowed to put their REST resources in their own namespace.)
Thoughts? This change will happen (for the App Framework module) in the next week or less if nobody convinces us otherwise.
I think my vote would be somewhat in the middle, and we take a similar approach to how we treat modules. For example, we put the “event” and “calculation” modules in the “org.openmrs.event” and “org.openmrs.calculation” packages as they were determined by community consensus to be part of the core platform, and the community processes are able to exert some level of control over these to make sure there are no overlapping packages.
Similarly, for established community modules, the community should be able to agree that we can allocate “core” URI (eg. “app” to appframework). But I think the default convention that we advertise to the average module author is to use the “moduleid/xyz” URI pattern.
I think the bar should be that a module actively intends to be used/available for the community (rather than a single group or distribution) and that it is generally considered to be the primary available or strategic solution for a given purpose.
I just didn’t want to enforce an arbitrary module ID rule and end up making things harder for module authors and less intuitive for developers using the REST API, figuring we historically have erred too often on being overly prescriptive. Module IDs work well for namespacing in Java code and URLs (which are rarely manually entered). I wasn’t sure that was true for REST URIs, which devs are more often entering manually into code, so making them intuitive seemed more important.
That said, Mike’s suggestion of a compromise is probably our best option: a general convention and path of least resistance for using module ID in the URI for namespacing but making it easy to override. So, for example, using the SDK to create a new module with REST resources would ask for a default base path for the URI with the module ID by default, so pressing Enter would use the module ID but typing /Enter would place resources in the root.
“v1” will change to “v2” when/if we need to make broad, backwards-incompatible changes to the REST API (e.g., changing conventions that affect all/many resources).
I agree with Mike’s suggestion that “core” modules (those modules that use org.openmrs.moduleid) can use something like /app… but I think we should continue with moduleid/resources URL pattern.
I like the idea that we can take a middle ground. I’d further say that it’s okay for module authors to make a judgment call on this, rather than it being “core” vs everything else. E.g. I would be perfectly fine with the appointmentscheduling module creating a top-level resource with a name like “scheduledappointment”, even though it’s not a core module. But no module should have a resource called “schedule” because this is definitely a confusing name.
