API Unification RFC

[ygrishajev]

Summary

This RFC proposes a unified approach to designing and structuring the API across the application. The goal is to improve consistency, clarity, and maintainability by standardizing endpoint naming, response formats, and resource access patterns. The proposal focuses on reducing ambiguity, avoiding deep resource nesting, and ensuring uniform permission handling.

Motivation

Currently, the API has inconsistencies that make it harder to use, maintain, and extend. Different endpoints follow varying conventions, response structures are inconsistent, and some routes rely on implicit assumptions (e.g., defaulting to the current user's context without explicit parameters). These inconsistencies lead to confusion, increased development time, and potential security issues.

The key motivations for this unification are:

• Consistency: Developers should be able to predict endpoint structures without constantly checking documentation.
• Clarity: Explicit resource paths and query parameters make the API easier to understand and use.
• Flexibility: A standardized interface accommodates various use cases, including organization-level and admin access, without complicating the API.
• Security: Consistent permission checks ensure that users only access resources they are authorized to view or modify.
• Maintainability: A unified approach reduces technical debt and simplifies future enhancements.

Examples

Below are examples highlighting existing issues and the proposed unified approach.

Example 1: Providers List Retrieval

Current:

GET /v1/providers

Response:

[
  { "id": "provider1", "name": "Provider One" },
  { "id": "provider2", "name": "Provider Two" }
]

• Issue: Returns a raw array without a consistent wrapper.

Proposed:

GET /v1/providers

Response:

{
  "data": [
    { "id": "provider1", "name": "Provider One" },
    { "id": "provider2", "name": "Provider Two" }
  ]
}

• Improvements:
  • Consistent wrapping with a data field for all list endpoints.
  • Easier to evolve api without breaking changes.

---

Example 2: Templates List Retrieval

Current:

GET /v1/templates-list

Response:

{
  "data": [
    { "id": "template1", "name": "Template One" },
    { "id": "template2", "name": "Template Two" }
  ]
}

• Issue: Inconsistent naming with an unnecessary -list suffix.

Proposed:

GET /v1/templates

• Improvements:
  • Simplified and RESTful endpoint naming.
  • Consistent across similar resource collections.

---

Example 3: User Settings Update (Permissions Use Case)

Current:

PUT /user/updateSettings

• Issues:
  • Ambiguous resource targeting.
  • Implicit assumption of current user context.

Proposed:

PUT /v1/users/:userId

• Improvements:
  • Clear resource identification with :userId.
  • Permissions are validated server-side to ensure the caller is authorized.
  • Supports use cases where the requester may have organization-level or admin access, not necessarily being the resource owner.

---

Example 4: Template Retrieval with Filters (Relation Filtering via Query Parameters)

Current:

GET /user/template/:id

• Issues:
  • Assumes templates are always requested for the current user.
  • Resource hierarchy is not clear and doesn't scale well.
  • Hard to extend for cases like admin or organization-level access.

Proposed:

GET /v1/templates?userId={userId}&favorite=true

• Key Points:
  • Flat structure: No deep nesting like /users/:userId/templates.
  • Optional query parameters: userId and favorite can be provided but are not required.
  • Permissions: Without userId, the endpoint returns results filtered by the caller’s permissions. Including userId enables scenarios like admin views or organization-wide access.
  • Flexibility: Easy to extend with additional filters without changing the endpoint structure.

---

Example 5: Template Creation (Mutation Standardization)

Current:

POST /users/saveTemplate

• Issues:
  • Endpoint name implies a user-specific action rather than a resource creation.
  • Inconsistent with RESTful conventions.

Proposed:

POST /v1/templates

• Improvements:
  • Aligns with RESTful standards where POST creates a resource.
  • Targets the resource directly without unnecessary user context.
  • Permissions are validated based on the requester's rights to create templates.

---

Example 6: Business Flow Commands (Command-like Endpoints)

While the goal is to standardize around resource-based endpoints, there are cases where command-like endpoints are more appropriate. These endpoints represent actions or business flows where the resource context is not clear or is secondary.

Example:

POST /v1/start-trial

• Why it’s acceptable:
  • Reflects a business process rather than a resource.
  • Command endpoints should be used sparingly and only when resource-based routes don't make sense.
  • Such endpoints should be consistently named and documented to avoid confusion.

---

Next Steps

1. Review and provide feedback on this RFC.
2. Align on naming conventions, response formats, and permission handling strategies.
3. Plan and execute the refactor in phases to minimize disruptions.
4. Update documentation and client code accordingly.

---

This unified approach will enhance the developer experience, improve maintainability, and ensure the API is scalable and secure for future needs. Feedback and suggestions are welcome!

[stalniy]

I think we need to split this into multiple suggestions

[stalniy]

I think there are more agreeable examples and those which requires discussion.

Like the ones which changes api not to rely on logged in user context.

From API perspective, if we implement things which are not allowed by default, we open a surface for security attacks. Like guessing user id and trying to access his resources. I know that we have permissions management but still opening things which we don’t use, introduce additional risks

[ygrishajev]

how high/distant is the probability of introducing sass like organisation into the console? @anilmurty @baktun14
this is relevant to the thread

[stalniy]

I think that org or admin level routes still may require changes. For example, an API for list of users may return different response on org level. Something what on lower level won’t be exposed

[ygrishajev]

so you're suggesting different endpoints for own endpoints an management-like ones? it actually makes sense. However this would probably make sense for user endpoints only. I think this is a naming issue. E.g. all own user endpoints could be renamed to me.

GET /v1/me
POST /v1/me

for other endpoints it doesn't make that much difference at the current moment as permissions would limit queries anyway.

[stalniy]

yes, I assume that response may be different for org admin users

[jzsfkzm]

Wrapping meaningful data to data comes in play when we want to make a listing endpoint do pagination (which we eventually should for most, I guess). So response would be {data: Resource[], pagination: PaginationInfo}.
I like this approach, but I guess that's no news for you @ygrishajev. How about response of non-listing endpoints, like GET /v1/me? And how about payloads of POST and PATCH endpoints? I see examples with and without wrapping for a patching endpoint.

What I'd like to add, quickly checked and didn't find bad examples, but we should keep it that way:

• Endpoints updating a resource should accept partial records and update those fields only, using the PATCH method:
  ❌ POST /v1/apples/:id HTTP method is misleading
  ❌ PATCH /v1/apples/:id if can only work with a full data
  ✅ PATCH /v1/apples/:id if can handle partial data

• Endpoints deleting a resource should use the DELETE method:
  ❌ POST /v1/delete-apple/:id our action verb is in the path
  ✅ DELETE /v1/apples/:id verb: method, noun: path, all clear

This leads me to your 6. point, I think we should keep number of those kind of endpoints to the minimum, or try and order those under our regular paths, wherever it makes sense. Don't want to hammer the cube in the round hole, but your example, POST /v1/start-trial might as well be POST /v1/users/trial too, isn't it? Each such case is a matter of discussion, balance, and judgement, of course.

[ygrishajev]

I have just provided examples.

So yea data wrapping should be there for all endpoints indeed imo.
I agree to the rest of following examples.

Regarding start-trial example. It's not referring to a resource. It actually implements a business flow manipulating multiple resources and 3rd party integrations. It's intended to be hidden behind a single endpoint due to its dynamic nature. This is really more of a command. Imo such things can't be avoided, so should be accepted.

[baktun14]

I agree with the suggestions, perhaps to split it into smaller chunks we could start by refactoring each endpoints in routes individually in the new module architecture. However, how do you see organizing for multiple api versions? Previously the idea was to put everything under /v1/* and then /v2/* but now all the routes are in individual modules.

[baktun14]

If we change all the routes and structure, it should be under /v2/*

[ygrishajev]

This discussion is about outer
Interface. However I don't find current approach helpful. There are issues already:

• The need for different swagger docs/pages or the need to merge the somehow
• Same domain/context entities spread across different places
• In both of the cases above it's confusing and introduces a (imo hight) probability of being missed

I believe:

• All routes should go as flat as possible in terms of hono router instances
• Prefixes should be defined in the route definition where it is actually helpful for the context
• Same routes of different versions should be placed along each other. E.g.

foo/
foo.v1.route.ts
foo.v2.route.ts