REST API端点动词转名词形式的改造方案咨询

Great question! When designing RESTful APIs, we want to center our design around resources (nouns) rather than discrete actions (verbs)—this aligns with REST's core principle of interacting with and manipulating resources. Let’s walk through practical, idiomatic ways to refactor your verb-heavy endpoints into noun-based patterns that follow industry best practices.

Option 1: Update the Container's State (Most RESTful Approach) #

Treat the container's operational state as a property of the container resource itself. Use a single PUT endpoint to modify this state, keeping your API focused on the resource instead of isolated actions.

Example Endpoint: #

PUT /container/{vendorID}/{pluginID}/{containerName}

Request Body (JSON): #

For starting the container:

{
  "status": "started"
}

For restarting:

{
  "status": "restarted"
}

For stopping:

{
  "status": "stopped"
}

Why this works: #

• It’s true to REST’s resource-first philosophy: you’re modifying the state of an existing resource (the container).
• PUT is idempotent (repeating the same request has the same effect), which is perfect for state changes like start/stop (if the container is already running, re-sending the started state won’t cause unintended side effects).
• For non-idempotent actions like restart (each call triggers a restart even if the container was already running), swap PUT for POST to signal the action isn’t repeat-safe.

Option 2: Use an "Actions" Subresource #

If you prefer to group operational actions under a dedicated subresource (useful for future extensibility), create an actions subresource and use POST to trigger specific actions. This keeps your main container endpoint clean for core CRUD operations.

Example Endpoint: #

POST /container/{vendorID}/{pluginID}/{containerName}/actions

Request Body (JSON): #

{
  "action": "start"
}

Or for restart/stop:

{
  "action": "restart"
}

Why this works: #

• It neatly bundles all operational actions for the container in one logical place.
• POST is ideal here because actions like restart are non-idempotent (each request alters the resource’s state in a unique way).
• You can easily extend this pattern later (e.g., adding pause, unpause, or delete actions without cluttering your main endpoints).

Option 3: Target the State as a Standalone Subresource #

Another clear variation is to treat the container's state as its own subresource. This makes the intent of the request even more explicit.

Example Endpoint: #

PUT /container/{vendorID}/{pluginID}/{containerName}/state

Request Body (JSON): #

{
  "value": "started"
}

Why this works: #

• It leaves no ambiguity: the request is explicitly updating the container’s operational state.
• This pattern shines if state management is a core part of your container API and you want to separate state updates from other container properties (like configuration changes).

Key Takeaways from Your Original Endpoints #

Your current endpoints (/start, /restart, /stop) are verb-focused, which deviates from REST’s resource-first design. By refactoring to noun-based patterns, you’ll make your API more intuitive, scalable, and consistent with how other developers expect REST APIs to work.

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