[PATCH 01/17] REST: Add additional documentation

[Stephen Finucane]

On Fri, 2018-11-09 at 00:15 +1100, Daniel Axtens wrote:
> Stephen Finucane <stephen at that.guru> writes:
> 
> > As noted in the Django REST Framework docs [1], views that support
> > multiple methods can and should split their documentation using
> > 'method:' style delimiters. Do just this.
> > 
> > [1] https://www.django-rest-framework.org/topics/documenting-your-api/#documenting-your-views
> > 
> > Signed-off-by: Stephen Finucane <stephen at that.guru>
> > ---
> >  patchwork/api/check.py   |  8 +++++++-
> >  patchwork/api/index.py   |  1 +
> >  patchwork/api/patch.py   | 10 +++++++++-
> >  patchwork/api/project.py | 11 ++++++++++-
> >  patchwork/api/user.py    | 11 ++++++++++-
> >  5 files changed, 37 insertions(+), 4 deletions(-)
> > 
> > diff --git a/patchwork/api/check.py b/patchwork/api/check.py
> > index 48019e72..4771455f 100644
> > --- a/patchwork/api/check.py
> > +++ b/patchwork/api/check.py
> > @@ -74,7 +74,13 @@ class CheckMixin(object):
> >  
> >  
> >  class CheckListCreate(CheckMixin, ListCreateAPIView):
> > -    """List or create checks."""
> > +    """
> > +    get:
> > +    List checks.
> > +
> > +    post:
> > +    Create a check.
> > +    """
> >  
> >      lookup_url_kwarg = 'patch_id'
> >      ordering = 'id'
> > diff --git a/patchwork/api/index.py b/patchwork/api/index.py
> > index 2266635c..45485c91 100644
> > --- a/patchwork/api/index.py
> > +++ b/patchwork/api/index.py
> > @@ -11,6 +11,7 @@ from rest_framework.views import APIView
> >  class IndexView(APIView):
> >  
> >      def get(self, request, *args, **kwargs):
> > +        """List API resources."""
> >          return Response({
> >              'projects': reverse('api-project-list', request=request),
> >              'users': reverse('api-user-list', request=request),
> > diff --git a/patchwork/api/patch.py b/patchwork/api/patch.py
> > index 6367dd5d..523378da 100644
> > --- a/patchwork/api/patch.py
> > +++ b/patchwork/api/patch.py
> > @@ -188,8 +188,16 @@ class PatchList(ListAPIView):
> >  
> >  
> >  class PatchDetail(RetrieveUpdateAPIView):
> > -    """Show a patch."""
> > +    """
> > +    get:
> > +    Show a patch.
> > +
> > +    patch:
> > +    Update a patch.
> >  
> > +    put:
> > +    Update a patch.
> I thought put created a patch/project/person. Does it also serve to
> update one? I know we got an issue via the mailing list about put vs
> update; should the docs make the distinction a bit clearer?

This is how django-rest-framework and most other APIs think about these
verbs.

GET
   Get an existing resource.

DELETE
   Delete an existing resource.

POST
   Create a new resource.

PUT
   Update an existing resource by sending the entire resource with
   updated values.

PATCH
   Update an existing resource by sending just the updated fields [*].

So saying that PUT updates a patch is correct.

Stephen

[*] Technically PATCH is supposed to contain instructions on updating
the resource, rather than just the updated fields, as noted in the
below article. However, I've never seen this done in practice and as
that article now notes, a new RFC - RFC 7396 - describes how people
*actually* do this stuff.

  https://williamdurand.fr/2014/02/14/please-do-not-patch-like-an-idiot/


> Apart from that, LGTM.
> 
> Regards,
> Daniel
> 
> > +    """
> >      permission_classes = (PatchworkPermission,)
> >      serializer_class = PatchDetailSerializer
> >  
> > diff --git a/patchwork/api/project.py b/patchwork/api/project.py
> > index 22fb1c4e..d7bb1f21 100644
> > --- a/patchwork/api/project.py
> > +++ b/patchwork/api/project.py
> > @@ -74,6 +74,15 @@ class ProjectList(ProjectMixin, ListAPIView):
> >  
> >  
> >  class ProjectDetail(ProjectMixin, RetrieveUpdateAPIView):
> > -    """Show a project."""
> > +    """
> > +    get:
> > +    Show a project.
> > +
> > +    patch:
> > +    Update a project.
> > +
> > +    put:
> > +    Update a project.
> > +    """
> >  
> >      pass
> > diff --git a/patchwork/api/user.py b/patchwork/api/user.py
> > index e11bed4b..29944e22 100644
> > --- a/patchwork/api/user.py
> > +++ b/patchwork/api/user.py
> > @@ -48,6 +48,15 @@ class UserList(UserMixin, ListAPIView):
> >  
> >  
> >  class UserDetail(UserMixin, RetrieveUpdateAPIView):
> > -    """Show a user."""
> > +    """
> > +    get:
> > +    Show a user.
> > +
> > +    patch:
> > +    Update a user.
> > +
> > +    put:
> > +    Update a user.
> > +    """
> >  
> >      pass
> > -- 
> > 2.17.2
> > 
> > _______________________________________________
> > Patchwork mailing list
> > Patchwork at lists.ozlabs.org
> > https://lists.ozlabs.org/listinfo/patchwork