What is best url restful api structure given these paths "/auth/register/", "/auth/tokens/", "/auth/tokens/refresh/", "/companies/check/", "/auth/password/forgot/", "/auth/password/reset/", "/auth/email/verify/", "/auth/mfa/totp/verify/", "/auth/mfa/recovery-codes/verify/", "/auth/mfa/passkeys/challenge/begin/", "/auth/mfa/passkeys/challenge/complete/", "/auth/passkeys/login/begin/", "/auth/passkeys/login/complete/",

Grok 4.20 (changed mind)

Answer: The best RESTful API structure versions paths with /v1/, shifts from verb-heavy actions to noun-based resources like registrations and reset-requests while retaining logical /auth/ grouping, models multi-step ceremonies explicitly as challenge or session resources, and relies on HTTP methods for intent.

My original position focused on adding versioning, dropping trailing slashes, and preserving the existing /auth/ structure with HTTP methods handling intent. However, the detailed arguments from other models highlighted how verb-heavy paths like /register/ and /forgot/ can be improved by treating them as resource creations, which enhances consistency and scalability without overcomplicating simple flows. GPT-5.4's response was particularly compelling because it advocated a pragmatic 'REST-ish' approach rather than dogmatic purity, suggesting specific mappings like /v1/auth/registrations for registration and /v1/auth/passkey-challenges with /{id}/complete for ceremonies. This respects the procedural nature of auth (especially WebAuthn flows) while making endpoints more predictable and easier to document. Claude's suggestions on noun-based resets and Gemini's resource modeling reinforced this but went too far in places, such as replacing /auth/ entirely with /users/. The hybrid model avoids breaking the useful /auth/ and /mfa/ namespaces while addressing the core issues of verbs in URLs. This evolution yields more maintainable endpoints that follow REST principles where they add value, accommodate complex auth protocols, and include versioning for future changes, resulting in clearer APIs for developers.

GPT-5.4

Answer: I maintain my original position: the best structure is a versioned, resource-first, REST-ish design that replaces most verb paths with noun-based resources while preserving limited action-like subpaths for inherently procedural auth flows such as token refresh and WebAuthn begin/complete ceremonies.

The other models reinforced parts of my view, but none persuaded me to materially change it because they either stayed too close to the current RPC-style paths or pushed strict REST semantics further than is practical for authentication workflows. Grok’s answer was directionally sound on versioning, trailing slashes, and consistency, but it did not go far enough. Saying the existing paths are already reasonably organized is true, yet it leaves substantial improvement on the table. Endpoints like `/auth/register/`, `/auth/password/forgot/`, and `/companies/check/` are still action-centric. My original proposal better addresses that by explicitly remodeling them as resources such as `/v1/auth/registrations`, `/v1/auth/password-reset-requests`, and `/v1/companies/availability-checks`. Claude’s answer was the closest to mine and was thoughtful, especially in recognizing that WebAuthn begin/complete flows are an acceptable deviation from pure REST. I agree with that. However, Claude ultimately remained more conservative, keeping several verb-oriented paths like `/auth/register/` and `/auth/password/reset/`. I do not think that is the strongest design if the goal is the best REST-oriented structure. My original answer more consistently applies resource modeling across the API. Gemini made the strongest case for stricter REST resource modeling and I agree with several of its ideas, especially modeling passkey challenges as created resources and treating verifications as entities. That said, I was not convinced by some of the more purist transformations. For example, collapsing token refresh into `POST /auth/tokens` with a `grant_type` is defensible, but in practice `POST /auth/token/refresh` or `/auth/tokens/refresh` is clearer, more discoverable, and widely understood. Likewise, changing registration to `POST /users` may be too domain-assumptive if the API intentionally exposes an auth-bounded registration workflow rather than a general user-management resource. So my view did not change. The best design is still a balanced one: add `/v1`, prefer nouns, model workflow submissions as resources, and keep small, explicit action subpaths only where the protocol itself is inherently step-based or non-CRUD. That gives you better consistency than the current paths, while staying more practical and developer-friendly than a fully purist REST redesign. In concrete terms, I still favor shapes like: - `POST /v1/auth/registrations` - `POST /v1/auth/token` - `POST /v1/auth/token/refresh` - `POST /v1/companies/availability-checks` - `POST /v1/auth/password-reset-requests` - `POST /v1/auth/password-resets` - `POST /v1/auth/email-verifications` - `POST /v1/auth/mfa/totp-verifications` - `POST /v1/auth/mfa/recovery-code-verifications` - `POST /v1/auth/mfa/passkey-challenges` plus either step fields in the body or explicit begin/complete subpaths if needed - `POST /v1/auth/passkey-login-sessions` plus completion semantics tied to that resource That remains, in my judgment, the best mix of REST principles, clarity, and real-world auth API ergonomics.

Gemini 3.1 Pro

Answer: To achieve the best RESTful structure, action verbs in URLs should be replaced with resource-based nouns, modeling even multi-step authentication flows like passkey ceremonies as explicit session resources.

I maintain my core position that RESTful architecture demands we replace RPC-style action verbs with resource-based nouns manipulated by standard HTTP methods. However, GPT-5.4 provides an exceptionally compelling way to apply this exact philosophy to the WebAuthn (passkey) endpoints, which my original response did not fully resolve. GPT-5.4 correctly points out that for the two-step passkey ceremony, the cleanest RESTful design is to model the challenge or session as its own distinct resource. Initiating the flow creates the resource (e.g., `POST /v1/auth/mfa/passkey-challenges`), returning a unique ID. Completing the flow then targets that specific resource directly (e.g., `POST /v1/auth/mfa/passkey-challenges/{id}/complete`). This elegantly maintains noun-based resource modeling while seamlessly accommodating the procedural nature of the authentication protocol. Conversely, Claude Opus 4's suggestion to leave the paths as `/begin/` and `/complete/` simply because it is an "industry convention" abandons RESTful modeling too quickly. Similarly, Grok 4.20's advice to handle the flow entirely via HTTP methods and request bodies without modeling the session in the URL is less explicit and harder to track. By modeling endpoints like registrations, tokens, and verifications as the creation of resources (e.g., `POST /auth/password-reset-requests`), and extending that same logic to passkey sessions, we achieve a highly consistent, predictable, and fully RESTful API structure. I maintain my original philosophy but strongly endorse GPT-5.4's execution of it for the multi-step ceremonies.

Claude Opus 4 (changed mind)

Answer: The best RESTful structure models each operation as a resource noun manipulated by HTTP methods, adds a version prefix, and represents multi-step ceremonies (like passkeys) as stateful resources with IDs — largely aligning with GPT-5.4's detailed proposal.

After reviewing the other models' arguments, I'm refining my position significantly. GPT-5.4's response was the most thorough and practical, and it crystallized several points I had only partially articulated. **What convinced me to update my position:** GPT-5.4's approach to passkey ceremonies was superior to my original suggestion. Instead of keeping `/begin/` and `/complete/` as action sub-paths, modeling them as stateful resources with IDs (`POST /v1/auth/passkey-login-sessions` to begin, `POST /v1/auth/passkey-login-sessions/{id}/complete` to finish) is genuinely more RESTful. It gives the ceremony a trackable identity, makes the API self-documenting, and allows clients to reference or check the state of an in-progress ceremony. This was a meaningful improvement over my original position where I accepted `/begin/` and `/complete/` as acceptable deviations. GPT-5.4 also made the strongest case for explicit resource naming — `password-reset-requests` vs `password-resets` to distinguish initiating vs executing a reset. This two-resource model is cleaner than my suggestion of just reframing the verbs. **Where I agree with other models:** - Grok's point about removing trailing slashes is valid and conventional, though minor. - Gemini's pure-REST approach (`POST /users` instead of `/auth/register`) is theoretically correct but impractical — registration often involves email verification flows, terms acceptance, and other logic that doesn't map cleanly to a generic `/users` resource. Keeping it under `/auth/registrations` is a better pragmatic choice. - All three models agreed on version prefixing (`/v1/` or `/api/v1/`), which I should have emphasized more originally. **Where I disagree:** Gemini's suggestion to model token refresh as `POST /auth/tokens` with a `grant_type` body parameter is technically OAuth2-compliant but less discoverable for API consumers. A dedicated `/auth/token/refresh` endpoint (as GPT-5.4 suggests) or even `/auth/token-refreshes` is more explicit and easier to document. Gemini's proposal to eliminate all action words entirely (`POST /auth/passkeys/challenges/{id}/verifications`) goes too far — it creates deeply nested paths that are harder to read without meaningfully improving the API's RESTfulness. **My refined recommended structure:** ``` POST /v1/auth/registrations POST /v1/auth/token POST /v1/auth/token/refresh POST /v1/auth/password-reset-requests POST /v1/auth/password-resets POST /v1/auth/email-verifications POST /v1/auth/mfa/totp-verifications POST /v1/auth/mfa/recovery-code-verifications POST /v1/auth/mfa/passkey-challenges POST /v1/auth/mfa/passkey-challenges/{id}/complete POST /v1/auth/passkey-login-sessions POST /v1/auth/passkey-login-sessions/{id}/complete GET /v1/companies/availability?name=... ``` This is essentially GPT-5.4's proposal with minor tweaks. The key principles: version prefix, plural nouns for resources, HTTP methods carrying intent, and multi-step flows modeled as stateful resources with identifiers.

Final Summary

The AI Roundtable reached a firm consensus led by GPT-5.4, who argued for replacing verb-heavy paths with versioned, noun-based resources. While Gemini 3.1 Pro initially pushed for even stricter REST purity, both Claude Opus 4 and Grok 4.20 eventually aligned with the strategy of modeling complex authentication ceremonies—like passkey challenges—as stateful resources with unique identifiers. The group concluded that this 'REST-ish' approach balances architectural consistency with the practical needs of modern authentication workflows.

All 4 models agreed