基于Rest-Easy的VOIP应用非资源型操作REST URL命名咨询

Great question—let's break this down using REST best practices, especially since you’ve clarified that calls aren’t persisted as resources (that’s a critical detail for shaping the right approach!).

For Call Origination #

First, let’s evaluate your proposed options, then land on the most clean, scalable choices:

Why your initial options fall short: #

• /originate/numberA,numberB: Using commas to separate numbers works but lacks readability, and requires handling encoding if numbers include special characters (like + for country codes). Also, putting a verb (originate) directly at the root isn’t ideal for REST’s resource-first mindset, even for non-persisted actions.
• /originate/[numberA,numberB]: Square brackets are reserved characters in URLs, so they’d need to be URL-encoded (%5B and %5D). This adds unnecessary complexity for clients and makes the URL harder to read at a glance.
• /number/numberA/originate/numberB: This frames the action as a sub-operation of numberA, which semantically doesn’t fit—originating a call is a bidirectional action between two parties, not a resource belonging to numberA.

Recommended Approaches #

1. Preferred: POST with request body (most REST-compliant)

Since originating a call is an action (not creating a persistent resource), use a POST request to a dedicated endpoint, and pass the numbers in the request body (JSON format works best):

• URL: POST /calls/originate
• Request Body:

  {
    "from": "numberA",
    "to": "numberB"
  }
  

This approach is scalable—you can easily add more parameters later (like call timeout, audio settings, etc.) without changing the URL structure. It also keeps the URL clean and focused on the action’s context (calls).

2. Alternative: POST with query parameters (if you must include numbers in the URL)

If you need to surface the numbers in the URL (e.g., for debugging or specific client requirements), use query parameters instead of path segments:

• URL: POST /calls/originate?from=numberA&to=numberB
  This avoids encoding headaches and keeps the parameters explicit.

For Call Transfer #

The same logic applies here—transferring a call is an action, not a resource operation. The only extra consideration is identifying the active call to transfer. Since you don’t persist calls, you’ll likely need to pass either the original call parties plus the target number, or a temporary session ID generated when the call was originated.

Recommended Approaches #

1. If using session IDs (temporary call identifiers)

If your system generates a temporary session ID for active calls (even without persisting it), use this to target the call:

• URL: POST /calls/{sessionId}/transfer
• Request Body:

  {
    "target": "numberC"
  }
  

This is the cleanest option, as the session ID uniquely identifies the call to transfer.

2. If no session ID is available

Pass all relevant numbers in the request body:

• URL: POST /calls/transfer
• Request Body:

  {
    "originalCaller": "numberA",
    "originalCallee": "numberB",
    "target": "numberC"
  }
  

Key Takeaway #

For non-persisted actions like call origination and transfer, prioritize using POST requests to action-specific endpoints under a logical parent path (/calls). Keep dynamic parameters (like phone numbers) in the request body or as query parameters—avoid cramming them into path segments unless they’re identifying a specific resource (which calls aren’t, in your case).

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