7 added 329 characters in body
source | link

Since the request speaks of executing the list of executingtasks (tasks are the listresource that we're speaking of taskshere), then if the task group has been executedmoved forward to execution (that is, regardless of execution result), then it would be sensible that the response status will be 200 OK, because the request to execute the group succeeded. Otherwise, if there was a problem in fulfillingthat would prevent execution of the request totask group, such as failing validation executeof the task objects the task group, or some required service isn't available for example, then the response status should denote that error. Past that, when execution of the tasks commences, seeing as the tasks to perform are listed in the request body, then I would expect that the execution results will be listed in the response body.

The long, philosophical answer

You are experiencing this dilemma because you are diverting from what HTTP was designed for. Namely, youYou are not usinginteracting it to manage resources, rather, you are using it as means of remote method invocation (which is not very odd, however works poorly without a preconceived scheme).

Since the request speaks of executing the list of tasks, then if the task group has been executed (that is, regardless of execution result), then it would be sensible the response status will be 200 OK, because the request to execute the group succeeded. Otherwise, if there was a problem in fulfilling the request to execute the task group, then the response status should denote that error.

The long answer

You are experiencing this dilemma because you are diverting from what HTTP was designed for. Namely, you are not using it to manage resources, rather, you are using it as means of remote method invocation (which is not very odd, however works poorly without a preconceived scheme).

Since the request speaks of executing the list of tasks (tasks are the resource that we're speaking of here), then if the task group has been moved forward to execution (that is, regardless of execution result), then it would be sensible that the response status will be 200 OK. Otherwise, if there was a problem that would prevent execution of the task group, such as failing validation of the task objects, or some required service isn't available for example, then the response status should denote that error. Past that, when execution of the tasks commences, seeing as the tasks to perform are listed in the request body, then I would expect that the execution results will be listed in the response body.

The long, philosophical answer

You are experiencing this dilemma because you are diverting from what HTTP was designed for. You are not interacting it to manage resources, rather, you are using it as means of remote method invocation (which is not very odd, however works poorly without a preconceived scheme).

6 deleted 1154 characters in body
source | link

Since the request is tospeaks of executeexecuting the list of tasks, then if the task group has been executed (that is, regardless of execution result), then semantically speaking,it would be sensible the response status shouldwill be 200 OK, because the request to execute the group succeeded. Otherwise, if there was a problem in fulfilling the request to execute the task group, then the response status should denote that error.

You are experiencing this dilemma because of an incoherence between what you are doing anddiverting from what HTTP was designed for. When a URI (Unified Resource Identifier) diverts from being an identifier for a resource, and looks more like a name of a functionNamely, you are likely doing something wrong.

The short and direct answer is the right one if you were posting tasksnot using it to a queuemanage resources, howeverrather, you are using it as means of remote method invocation (which is not entirely coherent with the implied approach that your implementation has toward its HTTP APIvery odd, however works poorly without a preconceived scheme).

With the above being said, and without courage to turn this answer into a long opinionated guide, the following is an example for a URI scheme that came to mindconforms with the intention of sparking inspirationa resource management approach:

  • /tasks
    • GET responds with a list oflists all tasks, likely paginated via Query String
    • POST will addadds a single task to a queue, returning the task ID
  • /tasks/task/[id]
    • GET responds with the task's status, perhaps information about when it was queued and executed, its type and the rest of the properties
    • PUT if no task with that ID exists, then adds a single task with that ID, same request body as a POST to /tasks. If one exists, responds with appropriate status codetask's state object
    • DELETE if thecancels/deletes a task was not already executed, then cancel it. If it was executed, responds with appropriate status code
  • /tasks/groups
    • GET responds with a list oflists all task groups, likely paginated via Query String
    • POST receives an object with an array of the same body that /tasks would, along with other group-specific properties (or just that array property if no other properties). Responds with an object that contains the ID of theadds a group, along with an array of the IDs of the individual tasks.
  • /tasks/groups/group/[id]
    • GET responds with an object denoting the execution status for the entire group (i.e. whether execution finished for all tasks, or if there are still tasks executing), each individual task's status in an array, and more properties regarding that group if any (like when it was requested, when it was complete, etc). A request with ?awaitCompletion=true query string will respond when the group finishes execution.
    • PUT if no group with that ID exists, adds a group with that ID. Otherwise, responds with appropriate error status.task group's state
    • DELETE if there are still tasks executing incancels/deletes the task group, cancels them.

This structure talks about resources, not what to do with them. What is being done with resources is the concern of another service.

Another important point to make is that it's advisable to not block for very long in an HTTP request handler. Much like UI, an HTTP interface should be responsive -- in a timescale that is a few orders of magnitude slower (because this layer deals with IO).

Making the move toward designing an HTTP interface that strictly manages resources is likely as hard as moving work away from a UI thread when a button is clicked. It requires that the HTTP server communicates with other services to execute tasks rather than executing them in the request handler. This isn't a shallow implementation, it's a change in direction.


ExecutingSome examples of how such a single task and tracking progress:URI scheme would be used

Executing a single task and tracking progress:

Executing a single task and awaiting its completion

Executing a single task and awaiting its completion:

Executing a task group and tracking progress:

Executing a task group and tracking progress:

Requesting an execution for a task group and waiting for its completion:

Requesting an execution for a task group and waiting for its completion:

Why this proposed approach is hard given the current approach

The above scheme requires that the HTTP server communicates with other services to execute tasks rather than executing them in the request handler. This isn't a shallow implementation, it's a change in direction.

You generally don't want to block very long in an HTTP request handler. Much like UI, you want to be responsive. In a timescale that is a few orders of magnitude slower because you are dealing with IO.

Since the request is to execute the list of tasks, then if the task group has been executed (that is, regardless of execution result), then semantically speaking, the response status should be 200 OK because the request to execute the group succeeded. Otherwise, if there was a problem in fulfilling the request to execute the task group, then the response status should denote that error.

You are experiencing this dilemma because of an incoherence between what you are doing and what HTTP was designed for. When a URI (Unified Resource Identifier) diverts from being an identifier for a resource, and looks more like a name of a function, you are likely doing something wrong.

The short and direct answer is the right one if you were posting tasks to a queue, however it is not entirely coherent with the implied approach that your implementation has toward its HTTP API.

With the above being said, and without courage to turn this answer into a long opinionated guide, the following is an example for a URI scheme that came to mind with the intention of sparking inspiration:

  • /tasks
    • GET responds with a list of all tasks, likely paginated via Query String
    • POST will add a single task to a queue, returning the task ID
  • /tasks/task/[id]
    • GET responds with the task's status, perhaps information about when it was queued and executed, its type and the rest of the properties
    • PUT if no task with that ID exists, then adds a single task with that ID, same request body as a POST to /tasks. If one exists, responds with appropriate status code
    • DELETE if the task was not already executed, then cancel it. If it was executed, responds with appropriate status code
  • /tasks/groups
    • GET responds with a list of all task groups, likely paginated via Query String
    • POST receives an object with an array of the same body that /tasks would, along with other group-specific properties (or just that array property if no other properties). Responds with an object that contains the ID of the group, along with an array of the IDs of the individual tasks.
  • /tasks/groups/group/[id]
    • GET responds with an object denoting the execution status for the entire group (i.e. whether execution finished for all tasks, or if there are still tasks executing), each individual task's status in an array, and more properties regarding that group if any (like when it was requested, when it was complete, etc). A request with ?awaitCompletion=true query string will respond when the group finishes execution.
    • PUT if no group with that ID exists, adds a group with that ID. Otherwise, responds with appropriate error status.
    • DELETE if there are still tasks executing in the group, cancels them.

Executing a single task and tracking progress:

Executing a single task and awaiting its completion

Executing a task group and tracking progress:

Requesting an execution for a task group and waiting for its completion:

Why this proposed approach is hard given the current approach

The above scheme requires that the HTTP server communicates with other services to execute tasks rather than executing them in the request handler. This isn't a shallow implementation, it's a change in direction.

You generally don't want to block very long in an HTTP request handler. Much like UI, you want to be responsive. In a timescale that is a few orders of magnitude slower because you are dealing with IO.

Since the request speaks of executing the list of tasks, then if the task group has been executed (that is, regardless of execution result), then it would be sensible the response status will be 200 OK, because the request to execute the group succeeded. Otherwise, if there was a problem in fulfilling the request to execute the task group, then the response status should denote that error.

You are experiencing this dilemma because you are diverting from what HTTP was designed for. Namely, you are not using it to manage resources, rather, you are using it as means of remote method invocation (which is not very odd, however works poorly without a preconceived scheme).

With the above being said, and without courage to turn this answer into a long opinionated guide, the following is a URI scheme that conforms with a resource management approach:

  • /tasks
    • GET lists all tasks, paginated
    • POST adds a single task
  • /tasks/task/[id]
    • GET responds with a single task's state object
    • DELETE cancels/deletes a task
  • /tasks/groups
    • GET lists all task groups, paginated
    • POST adds a group of tasks
  • /tasks/groups/group/[id]
    • GET responds with a task group's state
    • DELETE cancels/deletes the task group

This structure talks about resources, not what to do with them. What is being done with resources is the concern of another service.

Another important point to make is that it's advisable to not block for very long in an HTTP request handler. Much like UI, an HTTP interface should be responsive -- in a timescale that is a few orders of magnitude slower (because this layer deals with IO).

Making the move toward designing an HTTP interface that strictly manages resources is likely as hard as moving work away from a UI thread when a button is clicked. It requires that the HTTP server communicates with other services to execute tasks rather than executing them in the request handler. This isn't a shallow implementation, it's a change in direction.


Some examples of how such a URI scheme would be used

Executing a single task and tracking progress:

Executing a single task and awaiting its completion:

Executing a task group and tracking progress:

Requesting an execution for a task group and waiting for its completion:

5 Expanded my thoughts, clarified direct answer
source | link

Executing a single task and tracking progress:

  • POST /tasks with the task to execute
    • GET /tasks/task/[id] until response object completed has positive value while showing current status/progress

Executing a single task and awaiting its completion

  • POST /tasks with the task to execute
    • GET /tasks/task/[id]?awaitCompletion=true until completed has positive value (likely has timeout, which is why this should be looped)

Executing a task group and tracking progress:

  • POST /tasks/groups with the group of tasks to execute
    • GET /tasks/groups/group/[groupId] until response object completed property has value, showing individual task status (3 tasks completed out of 5, for example)
  • Denote completion with last request results (Executed 5 tasks, 1 task failed)
  • POST /tasks/groups with the group of tasks to execute
    • GET /tasks/groups/group/[groupId]?awaitCompletion=true until responds with result that denotes completion (there's likely alikely has timeout on how long this will wait, which is why should be looped)

Why it's hard to accept this proposed approach is hard given the current approach

Executing a task group and tracking progress:

  • POST /tasks/groups with the group of tasks to execute
    • GET /tasks/groups/group/[groupId] until response object completed property has value, showing individual task status (3 tasks completed out of 5, for example)
  • Denote completion with last request results (Executed 5 tasks, 1 task failed)
  • POST /tasks/groups with the group of tasks to execute
    • GET /tasks/groups/group/[groupId]?awaitCompletion=true until responds with result that denotes completion (there's likely a timeout on how long this will wait)

Why it's hard to accept this

Executing a single task and tracking progress:

  • POST /tasks with the task to execute
    • GET /tasks/task/[id] until response object completed has positive value while showing current status/progress

Executing a single task and awaiting its completion

  • POST /tasks with the task to execute
    • GET /tasks/task/[id]?awaitCompletion=true until completed has positive value (likely has timeout, which is why this should be looped)

Executing a task group and tracking progress:

  • POST /tasks/groups with the group of tasks to execute
    • GET /tasks/groups/group/[groupId] until response object completed property has value, showing individual task status (3 tasks completed out of 5, for example)
  • POST /tasks/groups with the group of tasks to execute
    • GET /tasks/groups/group/[groupId]?awaitCompletion=true until responds with result that denotes completion (likely has timeout, which is why should be looped)

Why this proposed approach is hard given the current approach

4 Expanded my thoughts, clarified direct answer
source | link
3 Expanded my thoughts, clarified direct answer
source | link
2 added 268 characters in body
source | link
1
source | link