CTS2/doc/Resource Oriented Architecture

The CTS2 specification has been built "from the ground up" using the principles of Resource Oriented Architecture (ROA). "Resources Oriented Architecture (ROA) is an overall system design that embraces RESTful design philosophy. It has a lot of overlap with Services Oriented Architecture (decentralization and small interoperating services) but it means that instead of treating our functionality and data as service calls; we treat them as resources in the RESTful sense." @@cite: http://depts.washington.edu/ontheroa/?p=42 @@

@@add citations to Fielding's paper and Richardson and Ruby@@

The predecessors to the CTS2 specification were based on a more traditional containment model -- code systems contained code system versions, code system versions contained entity descriptions and associations, etc. @@ insert a diagram here @@ This model presents several issues, including:

1. Existence conditions -- a description of a code system version cannot exist without also having the description of the code system. Similarly, the description of an entity can't exist outside of the context of the describing code system version. While this is undoubtedly true, there is a huge distinction between saying that a describing code system version exists (true) and having the actual description at your disposal. The hierarchical model tends to force implementers into having to implement an entire system.
2. Identity -- the hierarchical model blurs the distinction between the description and the thing being described. A logical URL for an code system version in the hierarchical model might be http://organization.com/service/codesystem/SNOMEDCT/version/20130731, an entity, http://organization.com/service/codesystem/SNOMEDCT/version/20130731/entity/74400008, and a particular entity designation, http://organization.com/service/codesystem/SNOMEDCT/version/20130731/entity/74400008/designation/d1. How would one reference the SNOMED CT concept, Appendicitis, independent of describing version? How would one determine whether http://organization.com/service/codesystem/SNOMEDCT was the same code system as http://institution.edu/svcs/codesystem/SNOMEDCT or http://institution.edu/service/codesystem/SCT?
3. Dependence -- does the identity of entity 7440008 depend on a particular version of a code system? (no) Does the identity of the designation "Appendicitis (Finding)" depend on a particular entity (arguably, "yes". @@ footnote although some models such as the UMLS assign identifiers to designations (SUI's) to strings, the CTS2 model does not require this.

The primary target of the CTS2 specification was http REST. While the specification was required to address service oriented API's such as SOAP and POJO (or POPyO, POCO, etc.), the developers believed that the federated, distributed and scalable nature of the world wide web was an ideal platform for terminology services. Attempts to transform the LexGrid @@ref@@ model into REST led to the sort of issues encountered above and the CTS2 Architects decided to make a clean break and to build ROA into the underlying Platform Independent Model.

The CTS2 specification was based on the following principles: @@ excerpts from Richardson and Ruby @@

The specification decided which parts of a terminology service would be first class resources: @@ list (or reference) the CTS2 resources @@

The representation of each resource was then fleshed out. @@ note on the distinction between primary and secondary classes@@

The next thing that was recognized that was that every resource had to describe something -- the identity of the description was not the identity of the thing being described. If one could not logically distinguish the two, then one was probably not modeling a primary resource. The term about was introduced into the model to represent the actual resource identifiers.

Finally, we represented the links between resources. The philosophy of the CTS2 model was that, if the model was rendered as a http REST interface, one would be able to traverse all of the (known) links between resources without having to assemble a URL or a service call.