Repository: django-json-api/django-rest-framework-json-api

Issue:
naming style: JSONAPI prefix or not?
[This started as a misplaced comment thread in #467. Let's move it here.]

I have a naming question: Do we prefix everything with `JSONAPI` or override existing names in DRF? We now have both styles:
- DJA serializers override DRF's `HyperlinkedModelSerializer` and so on. The advantage is code written for DRF can upgrade to DJA by simply changing an import. The disadvantage is that it's easy to "forget" to change the import from `rest_framework` to `rest_framework_json_api`.
- DJA paginators are named `JSONAPIPageNumberPagination` instead of overriding DRF's `PageNumberPagination`. The advantage is that it's very obvious that this is DJA-specific. The disadvantage is that instead of changing one import, you have to change each class use instance.

The approach here could be either:
- [x] DJA `DefaultRouter` overriding DRF `DefaultRouter`. 
- [ ] DJA `JSONAPIDefaultRouter`

---

@sliverc replied:
> Yeah I know I have also noticed. As we had to make backwards incompatible changes for pagination we started to add the JSONAPI prefix to work around this. There were also other cases in the past where this was done.

> Actually I would prefer not to use `JSONAPI` prefix as it is already clear by the rest_framework_json_api module that it is imported from DJA. As you outlined this way someone can also easily switch between DRF and DJA version by simply changing the import.

> However this won't be easy to accomplish to go that direction to make it consistent and backwards compatible. Potentially we have to break this at some point.

> But for new things (actually haven't thought about that when reviewing the filter backends) we can easily leave out the `JSONAPI` prefix.

> What is your preference?

---

I replied:

>> As we had to make backwards incompatible changes for pagination

> I don't think there was actually a backwards compatibility issue here as if one wants to be backward compatible they would just use `rest_framework.pagination.PageNumberPagination`. (Likewise for LimitOffset.)

>> Potentially we have to break this at some point.

> I say sooner than later. In the last release (2.5.0), we used the prefix `JsonApi` for paginators which is already deprecated by #463. The backend filters are not yet in a released version so have never been "seen" by their JSONAPI-prefixed names.

> The only other instance I was able to find was `rest_framework_json_api.metadata.JSONAPIMetadata` which extends `rest_framework.metadata.SimpleMetadata`; This could easily be renamed (with deprecation) to `rest_framework_json_api.metadata.SimpleMetadata` which would more clearly show the inheritance as well.

> The only other prefix I saw like this is `JSONAPIMeta` serializer inner class which I think is required to stay that way to distinguish it from the `Meta` inner class. 

>> What is your preference?

> My preference is to put in the effort now:
> - [x] drop the JSONAPI prefix from #466 before merging it. We have an open question (https://github.com/django-json-api/django-rest-framework-json-api/pull/466#discussion_r213601201) around naming it as well.
> - [ ] new PR to back out the prefix changes done in #463 and eliminate the JsonApi prefix and add deprecation warnings for `page` vs. `page[number]` and `page_size` vs. `page[size]`. Or just document this as a breaking change: `page` and `page_size` were never correct JSON:API usage.
> - [ ] new PR to rename/deprecate `JSONAPIMetadata`.

> Do you agree?

---

@sliverc wrote:

> There is also `JSONAPISettings` which we could rename to `APISettings`.

> Also I have noticed that we are kind of getting into the habit to misuse some issues to discuss things which might be related but not actually the same issue.

> I think for outsiders to better follow and to better track issues (e.g. a PR should solve one issue and not a comment of an issue) it would be better to create new issues for this (in this case a new issue where discussion happens on JSONAPI prefix).

> I will also follow up on a issue for versioning and deprecation policy.


Discussion:
@sliverc We also missed renaming `JSONAPIOrderingFilter` back to `OrderingFilter` so I think we need to do that before 2.6.0 as well.

Resolving patch:
diff --git a/example/settings/dev.py b/example/settings/dev.py
--- a/example/settings/dev.py
+++ b/example/settings/dev.py
@@ -90,7 +90,7 @@
     ),
     'DEFAULT_METADATA_CLASS': 'rest_framework_json_api.metadata.JSONAPIMetadata',
     'DEFAULT_FILTER_BACKENDS': (
-        'rest_framework_json_api.filters.JSONAPIOrderingFilter',
+        'rest_framework_json_api.filters.OrderingFilter',
         'rest_framework_json_api.django_filters.DjangoFilterBackend',
     ),
     'TEST_REQUEST_RENDERER_CLASSES': (
diff --git a/rest_framework_json_api/filters/__init__.py b/rest_framework_json_api/filters/__init__.py
--- a/rest_framework_json_api/filters/__init__.py
+++ b/rest_framework_json_api/filters/__init__.py
@@ -1 +1 @@
-from .sort import JSONAPIOrderingFilter  # noqa: F401
+from .sort import OrderingFilter  # noqa: F401
diff --git a/rest_framework_json_api/filters/sort.py b/rest_framework_json_api/filters/sort.py
--- a/rest_framework_json_api/filters/sort.py
+++ b/rest_framework_json_api/filters/sort.py
@@ -4,7 +4,7 @@
 from rest_framework_json_api.utils import format_value
 
 
-class JSONAPIOrderingFilter(OrderingFilter):
+class OrderingFilter(OrderingFilter):
     """
     This implements http://jsonapi.org/format/#fetching-sorting and raises 400
     if any sort field is invalid. If you prefer *not* to report 400 errors for
@@ -40,5 +40,5 @@ def remove_invalid_fields(self, queryset, fields, view, request):
             else:
                 underscore_fields.append(format_value(item_rewritten, "underscore"))
 
-        return super(JSONAPIOrderingFilter, self).remove_invalid_fields(
+        return super(OrderingFilter, self).remove_invalid_fields(
             queryset, underscore_fields, view, request)


Test patch: