Skip to content

Commit

Permalink
updates API documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
smirolo committed Jun 17, 2024
1 parent 11eaa7c commit 83e2fa4
Show file tree
Hide file tree
Showing 9 changed files with 121 additions and 94 deletions.
2 changes: 1 addition & 1 deletion pages/api/assets.py
Original file line number Diff line number Diff line change
Expand Up @@ -129,7 +129,7 @@ def post(self, request, *args, **kwargs):
.. code-block:: http
POST /api/assets HTTP/1.1
POST /api/supplier-1/assets HTTP/1.1
responds
Expand Down
12 changes: 6 additions & 6 deletions pages/api/elements.py
Original file line number Diff line number Diff line change
Expand Up @@ -49,9 +49,8 @@
from ..mixins import AccountMixin, PageElementMixin, TrailMixin
from ..models import (PageElement, RelationShip, build_content_tree,
flatten_content_tree, Follow)
from ..serializers import (AssetSerializer, NodeElementSerializer,
NodeElementCreateSerializer, PageElementSerializer,
PageElementTagSerializer)
from ..serializers import (AssetSerializer, NodeElementCreateSerializer,
PageElementSerializer, PageElementTagSerializer)
from ..utils import validate_title
from .assets import process_upload

Expand Down Expand Up @@ -489,7 +488,7 @@ def delete(self, request, *args, **kwargs):
.. code-block:: http
DELETE /api/editables/alliance/content/boxes-enclosures/ HTTP/1.1
DELETE /api/editables/alliance/content/boxes-enclosures HTTP/1.1
"""
#pylint:disable=useless-super-delegation
return super(PageElementEditableDetail, self).delete(
Expand All @@ -505,7 +504,7 @@ def post(self, request, *args, **kwargs):
.. code-block:: http
POST /api/editables/alliance/content/boxes-enclosures/ HTTP/1.1
POST /api/editables/alliance/content/boxes-enclosures HTTP/1.1
.. code-block:: json
Expand Down Expand Up @@ -537,7 +536,7 @@ def put(self, request, *args, **kwargs):
.. code-block:: http
PUT /api/editables/alliance/content/boxes-enclosures/ HTTP/1.1
PUT /api/editables/alliance/content/boxes-enclosures HTTP/1.1
.. code-block:: json
Expand Down Expand Up @@ -709,6 +708,7 @@ class ImportDocxView(AccountMixin, PageElementMixin, generics.GenericAPIView):
"text": "Hello"
}
"""
schema = None # XXX currently disabled in API documentation
serializer_class = PageElementSerializer

def upload_image(self, request):
Expand Down
54 changes: 27 additions & 27 deletions pages/api/progress.py
Original file line number Diff line number Diff line change
Expand Up @@ -26,14 +26,15 @@

from deployutils.helpers import datetime_or_now
from rest_framework import response as api_response, status
from rest_framework.exceptions import ValidationError
from rest_framework.generics import DestroyAPIView, ListAPIView, RetrieveAPIView

from .. import settings
from ..compat import gettext_lazy as _
from ..docs import extend_schema
from ..mixins import EnumeratedProgressMixin, SequenceProgressMixin
from ..models import EnumeratedElements, EnumeratedProgress, LiveEvent
from ..serializers import (EnumeratedProgressSerializer,
AttendanceInputSerializer)
from ..serializers import EnumeratedProgressSerializer


class EnumeratedProgressListAPIView(SequenceProgressMixin, ListAPIView):
Expand All @@ -58,8 +59,8 @@ class EnumeratedProgressListAPIView(SequenceProgressMixin, ListAPIView):
"previous": null,
"results": [
{
"created_at": "2020-09-28T00:00:00.0000Z",
"rank": 1,
"content": "ghg-emissions-scope3-details",
"viewing_duration": "00:00:00"
}
]
Expand Down Expand Up @@ -148,8 +149,8 @@ class EnumeratedProgressRetrieveAPIView(EnumeratedProgressMixin,
.. code-block:: json
{
"created_at": "2020-09-28T00:00:00.0000Z",
"rank": 1,
"content": "metal",
"viewing_duration": "00:00:00"
}
"""
Expand Down Expand Up @@ -177,7 +178,7 @@ def post(self, request, *args, **kwargs):
{
"rank": 1,
"created_at": "2020-09-28T00:00:00.0000Z",
"content": "metal",
"viewing_duration": "00:00:56.000000"
}
"""
Expand Down Expand Up @@ -218,18 +219,15 @@ class LiveEventAttendanceAPIView(EnumeratedProgressRetrieveAPIView):
.. code-block:: json
{
"created_at": "2020-09-28T00:00:00.0000Z",
"rank": 1,
"viewing_duration": "00:00:00"
"content":"ghg-emissions-scope3-details",
"viewing_duration": "00:00:00",
"min_viewing_duration": "00:01:00"
}
"""
rank_url_kwarg = 'rank'

def get_serializer_class(self):
if self.request.method.lower() == 'post':
return AttendanceInputSerializer
return super(LiveEventAttendanceAPIView, self).get_serializer_class()

@extend_schema(request=None)
def post(self, request, *args, **kwargs):
"""
Marks a user's attendance to a live event
Expand All @@ -243,31 +241,33 @@ def post(self, request, *args, **kwargs):
.. code-block:: http
POST /api/attendance/alliance/ghg-accounting-training/1/steve HTTP/1.1
POST /api/attendance/alliance/ghg-accounting-training/1/steve \
HTTP/1.1
responds
.. code-block:: json
{
"detail": "Attendance marked successfully"
"rank": 1,
"content":"ghg-emissions-scope3-details",
"viewing_duration": "00:00:00",
"min_viewing_duration": "00:01:00"
}
"""
serializer = self.get_serializer(data=request.data)
serializer.is_valid(raise_exception=True)

progress = self.get_object()
element = progress.step
live_event = LiveEvent.objects.filter(element=element.content).first()

# We use if live_event to confirm the existence of the LiveEvent object
if (live_event and
progress.viewing_duration <= element.min_viewing_duration):
progress.viewing_duration = element.min_viewing_duration
progress.save()
return api_response.Response(
{'detail': 'Attendance marked successfully'},
status=status.HTTP_200_OK)
return api_response.Response(
{'detail': 'Attendance not marked'},
status=status.HTTP_400_BAD_REQUEST)
if (not live_event or
progress.viewing_duration > element.min_viewing_duration):
raise ValidationError(_("Cannot mark attendance of %(user)s"\
" to %(sequence)s:%(rank)s.") % {
'user': self.user, 'sequence': self.sequence,
'rank': self.kwargs.get(self.rank_url_kwarg)})

progress.viewing_duration = element.min_viewing_duration
progress.save()
serializer = self.get_serializer(instance=progress)
return api_response.Response(serializer.data)
28 changes: 28 additions & 0 deletions pages/api/reactions.py
Original file line number Diff line number Diff line change
Expand Up @@ -273,6 +273,34 @@ def perform_create(self, serializer):


class NewsFeedListAPIView(UserMixin, generics.ListAPIView):
"""
Retrieves relevant news for a user
**Tags**: content
**Examples**
.. code-block:: http
GET /api/content/steve/newsfeed HTTP/1.1
responds
.. code-block:: json
{
"count": 1,
"next": null,
"previous": null,
"results": [{
"path": "/metal/boxes-and-enclosures/production/energy-efficiency/process-heating/combustion/adjust-air-fuel-ratio",
"text_updated_at": "2024-01-01T00:00:00Z",
"last_read_at": "2023-12-01T00:00:00Z",
"nb_comments_since_last_read": 5,
"descr": ""
}]
}
"""
serializer_class = PageElementUpdateSerializer

def get_queryset(self):
Expand Down
63 changes: 25 additions & 38 deletions pages/api/sequences.py
Original file line number Diff line number Diff line change
Expand Up @@ -32,8 +32,8 @@

from ..mixins import AccountMixin, SequenceMixin
from ..models import Sequence, EnumeratedElements
from ..serializers import (SequenceSerializer, SequenceCreateSerializer,
EnumeratedElementSerializer)
from ..serializers import (EnumeratedElementSerializer, SequenceSerializer,
SequenceUpdateSerializer, SequenceCreateSerializer)

LOGGER = logging.getLogger(__name__)

Expand All @@ -53,7 +53,7 @@ class SequencesIndexAPIView(ListAPIView):
.. code-block:: http
GET /api/sequences HTTP/1.1
GET /api/content/sequences HTTP/1.1
responds
Expand All @@ -66,7 +66,7 @@ class SequencesIndexAPIView(ListAPIView):
"results": [
{
"created_at": "2024-01-01T00:00:00.0000Z",
"slug": "ghg-accounting-training",
"slug": "ghg-accounting-webinar",
"title": "GHG Accounting Training",
"account": "djaopsp",
"has_certificate": true
Expand Down Expand Up @@ -117,7 +117,7 @@ class SequenceListCreateAPIView(AccountMixin, ListCreateAPIView):
"results": [
{
"created_at": "2020-09-28T00:00:00.0000Z",
"slug": "ghg-accounting-training",
"slug": "ghg-accounting-webinar",
"title": "GHG Accounting Training",
"account": "djaopsp",
"has_certificate": true
Expand Down Expand Up @@ -171,7 +171,7 @@ def post(self, request, *args, **kwargs):
.. code-block:: json
{
"slug": "ghg-accounting-training",
"slug": "ghg-accounting-webinar",
"title": "GHG Accounting Training"
}
Expand All @@ -181,7 +181,7 @@ def post(self, request, *args, **kwargs):
{
"created_at": "2023-01-01T04:00:00.000000Z",
"slug": "ghg-accounting-training",
"slug": "ghg-accounting-webinar",
"title": "GHG Accounting Training",
"account": null,
"has_certificate": true
Expand All @@ -206,36 +206,30 @@ class SequenceRetrieveUpdateDestroyAPIView(AccountMixin, SequenceMixin,
.. code-block:: http
GET /api/editables/alliance/sequences/ghg-accounting-training HTTP/1.1
GET /api/editables/alliance/sequences/ghg-accounting-webinar HTTP/1.1
responds
.. code-block:: json
{
"created_at": "2023-12-29T04:33:33.078661Z",
"slug": "ghg-accounting-training",
"slug": "ghg-accounting-webinar",
"title": "GHG Accounting Training",
"account": null,
"has_certificate": true,
"results": [
{
"rank": 1,
"content": "text-content",
"min_viewing_duration": "00:00:10"
},
{
"rank": 2,
"content": "survey-event",
"min_viewing_duration": "00:00:20"
}
]
"has_certificate": true
}
"""
serializer_class = SequenceSerializer
lookup_field = 'slug'
lookup_url_kwarg = SequenceMixin.sequence_url_kwarg

def get_serializer_class(self):
if self.request.method.lower() == 'put':
return SequenceUpdateSerializer
return super(SequenceRetrieveUpdateDestroyAPIView,
self).get_serializer_class()

def get_object(self):
return self.sequence

Expand All @@ -249,7 +243,7 @@ def delete(self, request, *args, **kwargs):
.. code-block:: http
DELETE /api/editables/alliance/sequences/ghg-accounting-training\
DELETE /api/editables/alliance/sequences/ghg-accounting-webinar\
HTTP/1.1
"""
Expand All @@ -265,7 +259,7 @@ def put(self, request, *args, **kwargs):
.. code-block:: http
PUT /api/editables/alliance/sequences/ghg-accounting-training HTTP/1.1
PUT /api/editables/alliance/sequences/ghg-accounting-webinar HTTP/1.1
.. code-block:: json
Expand All @@ -281,12 +275,11 @@ def put(self, request, *args, **kwargs):
{
"created_at": "2023-12-29T04:33:33.078661Z",
"slug": "ghg-accounting-training",
"slug": "ghg-accounting-webinar",
"title": "Updated GHG Accounting Training Title",
"account": null,
"has_certificate": false,
"extra": "Additional info",
"results": []
"extra": "Additional info"
}
"""
#pylint:disable=useless-parent-delegation
Expand All @@ -304,7 +297,9 @@ class AddElementToSequenceAPIView(AccountMixin, SequenceMixin,
.. code-block:: http
GET /api/editables/alliance/sequences/ghg-accounting-training/elements HTTP/1.1
GET /api/editables/alliance/sequences/ghg-accounting-webinar/elements HTTP/1.1
responds
.. code-block:: json
Expand All @@ -325,14 +320,6 @@ class AddElementToSequenceAPIView(AccountMixin, SequenceMixin,
}
]
}
responds
.. code-block:: json
{
"detail": "element added"
}
"""
serializer_class = EnumeratedElementSerializer

Expand All @@ -349,7 +336,7 @@ def post(self, request, *args, **kwargs):
.. code-block:: http
POST /api/editables/alliance/sequences/ghg-accounting-training/elements HTTP/1.1
POST /api/editables/alliance/sequences/ghg-accounting-webinar/elements HTTP/1.1
.. code-block:: json
Expand Down Expand Up @@ -415,7 +402,7 @@ class RemoveElementFromSequenceAPIView(AccountMixin, SequenceMixin,
**Example**
DELETE /api/editables/alliance/sequences/ghg-accounting-training/elements/1 HTTP/1.1
DELETE /api/editables/alliance/sequences/ghg-accounting-webinar/elements/1 HTTP/1.1
responds
Expand Down
1 change: 1 addition & 0 deletions pages/helpers.py
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,7 @@ def get_extra(obj, attr_name, default=None):
extra = obj.get('extra')
return extra.get(attr_name, default) if extra else default


def update_context_urls(context, urls):
if 'urls' in context:
for key, val in six.iteritems(urls):
Expand Down
Loading

0 comments on commit 83e2fa4

Please sign in to comment.