[PATCH 01/17] REST: Add additional documentation

[Daniel Axtens]

Stephen Finucane <stephen at that.guru> writes:

> 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.
>

Ok, thanks for that.

Regards,
Daniel

> 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