REST API创建记录接口两种URL结构设计方案选型咨询

Hey there! Let's walk through your two options and figure out which one makes the most sense for your use case.

Option 1: Unified Endpoint with Route Parameter (/api/create/auto & /api/create/manual) #

This approach uses a single function to handle both types, with auto/manual as a route parameter, and the request body carrying the corresponding data.

Pros #

• RESTful consistency: It aligns with REST principles by treating the record type as a modifier of the create operation, keeping your API surface clean and predictable.
• Better code reuse: You only need one handler function, with a simple branch to call the correct stored procedure. This cuts down on redundant code for shared logic like request parsing or error handling.
• Scalability: If you ever need to add a new record type later (like /api/create/batch), you just extend the parameter validation and add the corresponding stored procedure call—no need to create a whole new endpoint.

Cons #

• Extra validation step: You'll need to add a check to ensure the route parameter is only auto or manual, returning a 400 Bad Request for invalid values. That's a small overhead, but it's something to account for.
• Potential future bloat: If over time the logic for auto and manual diverges significantly (e.g., adding different validation rules or business logic), the single handler could become messy and hard to maintain.

Option 2: Separate Endpoints (/api/createauto & /api/createmanual) #

This approach uses two independent functions, each dedicated to one record type.

Pros #

• Clear separation of concerns: Each endpoint has a single, well-defined responsibility. Anyone looking at the API can immediately tell what each one does without digging into parameters.
• Low maintenance for simple logic: Since your current logic is just passing data to stored procedures, each handler will be straightforward and easy to debug. If the two types ever need to evolve differently, you can modify each endpoint without affecting the other.
• No parameter validation needed: The route itself enforces the type, so you don't have to worry about invalid values sneaking in.

Cons #

• API clutter: If you add more record types later, you'll end up with a long list of similar endpoints (createX, createY, etc.), which makes your API less intuitive to navigate.
• Code redundancy: Even with simple logic, you'll have duplicate code for shared tasks unless you extract them into helper functions, which adds extra setup steps.

Recommendation for Your Scenario #

Given that your current processing logic is simple and just involves passing data to different stored procedures, I'd lean towards Option 1 for a few reasons:

• The validation overhead is minimal (a quick check against a whitelist like ['auto', 'manual'] is all you need).
• It keeps your API clean and scalable, which is helpful if you ever expand the system.
• You avoid redundant code, making your codebase easier to maintain right now.

That said, if you're absolutely certain you'll never add more record types and want the most explicit, no-frills approach, Option 2 is also a solid choice—it's just less flexible long-term.

内容的提问来源于stack exchange，提问作者Ian Boggs