Updates API docs for clarity (#56)

keystone_api/apps/allocations/serializers.py

@@ -10,7 +10,7 @@
 
 from .models import *
 
-__all__ = ['AllocationSerializer', 'ClusterSerializer', 'ProposalSerializer']
+__all__ = ['AllocationSerializer', 'ClusterSerializer', 'ProposalSerializer', 'ProposalReviewSerializer']
 
 
 class ClusterSerializer(serializers.ModelSerializer):
@@ -35,3 +35,11 @@ class ProposalSerializer(serializers.ModelSerializer):
     class Meta:
         model = Proposal
         fields = '__all__'
+
+
+class ProposalReviewSerializer(serializers.ModelSerializer):
+    """Object serializer for the `ProposalReview` class"""
+
+    class Meta:
+        model = ProposalReview
+        fields = '__all__'

keystone_api/apps/allocations/urls.py

@@ -10,5 +10,6 @@
 router.register(r'clusters', ClusterViewSet)
 router.register(r'allocations', AllocationViewSet)
 router.register(r'proposals', ProposalViewSet)
+router.register(r'proposal-reviews', ProposalReviewViewSet)
 
 urlpatterns = router.urls

keystone_api/apps/allocations/views.py

@@ -9,25 +9,32 @@
 from .models import *
 from .serializers import *
 
-__all__ = ['AllocationViewSet', 'ClusterViewSet', 'ProposalViewSet']
+__all__ = ['AllocationViewSet', 'ClusterViewSet', 'ProposalViewSet', 'ProposalReviewViewSet']
 
 
 class ClusterViewSet(viewsets.ReadOnlyModelViewSet):
-    """Read-only JSON ViewSet for querying cluster database records"""
+    """Read-only JSON ViewSet for querying cluster database records."""
 
     queryset = Cluster.objects.all()
     serializer_class = ClusterSerializer
 
 
 class AllocationViewSet(viewsets.ModelViewSet):
-    """JSON ViewSet for querying allocation database records"""
+    """Manage SU allocations for user research groups."""
 
     queryset = Allocation.objects.all()
     serializer_class = AllocationSerializer
 
 
 class ProposalViewSet(viewsets.ModelViewSet):
-    """JSON ViewSet for querying proposal database records"""
+    """Manage project proposals used to request additional service unit allocations."""
 
     queryset = Proposal.objects.all()
     serializer_class = ProposalSerializer
+
+
+class ProposalReviewViewSet(viewsets.ModelViewSet):
+    """Manage project proposal reviews."""
+
+    queryset = ProposalReview.objects.all()
+    serializer_class = ProposalReviewSerializer

keystone_api/apps/health/urls.py

@@ -7,6 +7,6 @@
 app_name = 'health'
 
 router = DefaultRouter()
-router.register('', HealthCheckViewSet, basename='health')
+router.register('', HealthChecks, basename='health')
 
 urlpatterns = router.urls

keystone_api/apps/health/views.py

@@ -9,19 +9,22 @@
 from health_check.mixins import CheckMixin
 from rest_framework.viewsets import ViewSet
 
-__all__ = ['HealthCheckViewSet']
+__all__ = ['HealthChecks']
 
 
-class HealthCheckViewSet(CheckMixin, ViewSet):
+class HealthChecks(ViewSet, CheckMixin):
     """View for rendering system status messages"""
 
     def list(self, request: HttpRequest, *args, **kwargs) -> JsonResponse:
-        """Return a JSON responses detailing system status checks
+        """Return a JSON response detailing system status checks.
 
-        Functions similarly to the overloaded parent method, except responses
-        are forced to be JSON format and are never rendered HTML.
+        The returned status code will be 200 if all checks pass. If any checks
+        fail, the status code will be 500.
         """
 
+        # This method functions similarly to the overloaded parent method,
+        # except responses are forced to be JSON and never rendered HTML.
+
         status_code = 500 if self.errors else 200
         return self.render_to_response_json(self.plugins, status_code)
 

keystone_api/apps/research_products/views.py

@@ -3,6 +3,7 @@
 View objects handle the processing of incoming HTTP requests and return the
 appropriately rendered HTML template or other HTTP response.
 """
+from typing import overload
 
 from rest_framework import viewsets
 
@@ -13,14 +14,14 @@
 
 
 class PublicationViewSet(viewsets.ReadOnlyModelViewSet):
-    """ViewSet for querying cluster publication records"""
+    """Manage metadata for research publications."""
 
     queryset = Publication.objects.all()
     serializer_class = PublicationSerializer
 
 
 class GrantViewSet(viewsets.ReadOnlyModelViewSet):
-    """ViewSet for querying grant database records"""
+    """Track funding awards and grant information."""
 
     queryset = Grant.objects.all()
     serializer_class = GrantSerializer

keystone_api/main/urls.py

@@ -11,7 +11,7 @@
     path('allocations/', include('apps.allocations.urls', namespace='alloc')),
     path('authentication/', include('apps.authentication.urls', namespace='authentication')),
     path('health/', include('apps.health.urls', namespace='health')),
-    path('products/', include('apps.research_products.urls', namespace='research_products')),
+    path('research-products/', include('apps.research_products.urls', namespace='research_products')),
 ]
 
 if settings.DEBUG: