Stephen Finucane <[email protected]> writes: > On Fri, 2018-11-09 at 00:15 +1100, Daniel Axtens wrote: >> Stephen Finucane <[email protected]> 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 <[email protected]> >> > --- >> > 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 >> > [email protected] >> > https://lists.ozlabs.org/listinfo/patchwork _______________________________________________ Patchwork mailing list [email protected] https://lists.ozlabs.org/listinfo/patchwork
