Requiring format extension on all URLs

[Phil Gyford]

Hi,

I'm trying to set up DRF as a read-only API, and want to require that all URLs have either a .api or .json format extension.

I've sort of managed this so far by copying the DefaultRouter class and in its get_urls() method changing this call:

    urls = format_suffix_patterns(urls)

to this:

    urls = format_suffix_patterns(

        urls, suffix_required=True, allowed=["api", "json"]

    )

This gets me what I need but leaves me with two remaining/resulting issues:

1. Tbe API Root URL looks like /api/v1/.api or /api/v1/.json. I feel it shouldn't have that final slash but, given all non-API URLs on the site have an ending slash, and I include my API URL conf with path("api/v1/", include("myproject.api.urls", namespace="v1")), I can't see how to fix it.

2. When I view the Browsable API, using the .api extension URLs, the links in the Breadcrumbs do not have the extension, and so clicking them 404s. I can't see any way to fix this other than subclassing BrowsableAPIRenderer and using a modified utils.breadcrumbs.get_breadcrumbs function.

I didn't think this was an unreasonable thing to want – explicit URLs for each format – but given the amount of fiddling required to get it functioning, maybe this is a dumb idea? Have I missed something? How do you set up your URLs and formats?

Many thanks,

Phil Gyford

[Carl Nobile]

Hi Phil,

The best way to solve all these issues is to use mime types to determine the type of return data.

For example application/vnd.{company name}.{endpoint name}+json;ver=1.

In the above you would replace {company name} with your company or organization name, and {endpoint name} with something like account, customer, or whatever the specific endpoint would be.

The +json could also be +api in your case.

The ;ver=1 would indicate the version number.

So why is this better?

1. You no longer need /v1/ or /v2/ in the URI.
2. Each endpoint can have different versions independently of any other endpoint.
3. The type of data is defined by the mime type not by changing the URI.
4. You can send one type of data and receive another type. For example using different Accept and Content-Type headers.

This is the best way to do this and solves a lot of issues down the road, but it does require a bit more code written upfront.

~Carl

--
You received this message because you are subscribed to the Google Groups "Django REST framework" group.
To unsubscribe from this group and stop receiving emails from it, send an email to django-rest-fram...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/django-rest-framework/87e4d9e4-bde5-4285-ae66-dfdc32c3384bn%40googlegroups.com.

--

-------------------------------------------------------------------------------
Carl J. Nobile (Software Engineer)
carl....@gmail.com
-------------------------------------------------------------------------------

[Phil Gyford]

Thanks Carl. I'll think about your suggestion.

I'm a little hesitant as I usually try to do things the most conventional way, especially with a tool like DRF that I'm using for the first time. I want to go with the flow and do things the expected, "normal" way. The DRF docs are a little confusing about this topic, although, to my reading, they seem to go more for format extensions rather than Accept headers and mime types. (https://www.django-rest-framework.org/api-guide/format-suffixes/#accept-headers-vs-format-suffixes ).

But, as I said, having tried to enforce the use of format extensions – thinking this is more explicit (which I like) than having them be optional, or having optional ?format=<extension> query parameters  – I've ended up going down a path that feels wrong and excessive. Hence me trying to find out what's "normal", or most common.

Thanks again,

Phil

[Carl Nobile]

Phil,

The correct, normal, and common ways are not always the same as many people don't understand that RFCs define the correct way to do things, not a specific framework like DRF. The quick a dirty way will ALWAYS lead to issues down the road.

I use format queries also but only when maneuvering around the browsable API the DRF gives you, never for machine to machine access.

These are some of the standard documents:

https://datatracker.ietf.org/doc/html/rfc7231

https://datatracker.ietf.org/doc/html/rfc6839

https://datatracker.ietf.org/doc/html/rfc4288

Roy Fielding is the editor of many RFCs he's also the one that pretty much invented REST he's the editor of RFC7231 above.

Building a RESTful web service that is done properly is not easy. It takes planning and understanding best practices. This includes security concerns.

You should also read Roy Fielding dissertation on REST which can be found here: https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm

~Carl

To view this discussion on the web visit https://groups.google.com/d/msgid/django-rest-framework/cafb0a93-1920-4333-a3b0-6f71f700b45cn%40googlegroups.com.