Feedback on feat-headless

[foarsitter]

This week I discovered the progress you made on the headless project. I'm glad you made a proof of concept React app since I cannot agree more on your statement that you cannot designing an API without making your hands dirty.

My main concern is that, at the moment, allauth.headless isn't self documenting by providing an OpenAPI specification. I would like to share a single OpenAPI specification with my clients so they now how to interact with the API. In my case I'm using drf-spectacular for that.

What are your thoughts about that?

Another concern is about your app/browser & version prefix. When I'm including path("", include("allauth.headless.urls")) in my api router the urls are as following:

/api/app/v1/auth/login
/api/browser/v1/auth/login    

The versions prefix is something that I would like to so to be global to my API and not specific to the API endpoints. The way of authenticating (app vs browser) is something the endpoint would handle in the case of DRF. That again is global to my API and not specific to the auth endpoints.

The urls that should be the result of including allauth.headless should follow the following pattern In my opinion (without version or app/browser. Providing an version or not is up to the user.

/api/auth/login
/api/auth/password/request       
/api/account/authenticators      

To achieve this there should be tightly coupling with Django REST framework or Django Ninja I guess.

Feel free to reach out in private If you want to discuss this topic any further or if you want me to test something else. I like what you did so far and looking forward to use allauth.headless in production in the near future!

[pennersr]

Correct me if I am wrong, but I think that most of your comments result from your expectation that your project/app will offer one overall API. That expectation is indeed not met, intentionally:

• allauth cannot pick a side in the DRF vs Ninja debate. Its API should work with any project setup, and not favor one above the other.
• Even if we were to pick sides, the allauth API and whatever API your project is offering would match style wise. These are separate APIs, designed by separate people and purposes, and you would be able to tell right away, even if the same framework was used.

The allauth API is intentionally designed to just be that -- an authentication API. If your project/app requires additional endpoints, feel free to use whatever tool you would like. The headless implementation offers a pluggable access token method that bridges the gap between the allauth API and your API, but other than that, do treat the two as separate entities.

isn't self documenting by providing an OpenAPI specification

There is an OpenAPI specification: https://github.com/pennersr/django-allauth/blob/feat-headless/docs/headless/spec/openapi.yaml -- whether that is manually handcrafted, or automatically generated, should really not matter to you when integrating django-allauth. As long as there is a standards compliant specification that can e.g. be fed to OpenAPI client generators, the process behind that spec seems irrelevant to me?

The versions prefix is something that I would like to so to be global to my API and not specific to the API endpoints.

As mentioned above -- you are free to structure your API the way you would like. We cannot mix your version number with that of allauth. For example, suppose we need to break the allauth API at some future point in time. That is an issue local to allauth, and while allauth may need a new v2 login endpoint, your project endpoints would remain unaffected.

So the way it is designed, is that there are multiple APIs, and for each on of those, you will have a version number. For example, in the future there might be an additional "admin" API that allows access to the user data pool as a whole (next to the current user/authentication centric API that is app/browser), and that can follow its own version scheme.

The way of authenticating (app vs browser) is something the endpoint would handle in the case of DRF.

Also touched upon above. DRF is not in scope. But even then, from allauth point of view the 2 use cases have been intentionally separated into separate APIs. The rationale is that there are security concerns, and I prefer to tackle those by making it crystal clear by having to pick an endpoint, instead of offering endpoints that IMO obscure things and handle things in multiple ways.

To achieve this there should be tightly coupling with Django REST framework or Django Ninja I guess.

That is not an option.

In any case, I appreciate the feedback -- if I missed something just let me know.

[foarsitter]

Your explanation is crystal clear and, indeed, I was assuming that it would integrate with DRF and/or Ninja because that is what I'm looking for.

I sense we are on two totally different pages about the expectations of allauth-headless and since you are the author I leave it as it is.

Keep up to good work you are providing!