Page Comparison

...

In the RefApp, we currently have OpenAPI documentation (formerly called Swagger) of REST API endpoints that are both under-utilized and under-maintained. The documentation, which are both human and machine readable, can be valuable if they are completely and accurate. Besides giving developers an easy way to understand the API endpoints, it can be used to automatically generate REST API clients for the frontend, greatly reducing the boilerplate code that we need to make to do the same thingrequired.

The page documents the existing architecture of the REST module, the existing documentation around it, and the challenges we face to improve it.

...

• MainResorceController handles the request, determines which resource the request is for (PatientResource), and calls that resource's retrieve() function.

• DelegatingCrudResource (which is the superclass of most *Resource.java files) provides the retrieve function, which calls asRepresentation() to that reads the <rep> parameter

• asRepresentation() attempts to convert the <rep> to a list of Patient properties (fields) to be retrieved using a combination of different strategies:

  • PatientResource.getRepresentationDescription() is first called. This function (usually) lists out the properties that should be retrieved for the "standard" representations commons to most resources (default, full and ref).

  • if the above function returns null, the findAnnotatedMethodForRepresentation function is called to find the method in the *Resource.java class that is annotated with @RepHandler to handle the specified <rep>.

  • If the above fails, it assumes that the <rep> is a customer representation (ex: custom:(uuid)), and calls getCustomRepresentationDescription to retrieve the list of properties.

• The The BaseDelegatingConverter.'s convertDelegateToRepresentation() function gets called to loop through each property name and converts it to actual values by calling DelegatingResourceDescription.Property.evaluate()

• The evaluate() function tries a combination strategy of reflection and annotated methods to retrieve the value of the property. This process can be recursive as the property can itself be another Resource.

• The evaluated object gets returned by MainResourceController.retrieve() to be serialized into the appropriate data format (xml or json)

...