CODEWITHSUNDEEP
restapi-design
Roger Thomas
Roger Thomas

Reputation: 881

Increase the value of a field of a resource in a RESTful API by a fixed amount without knowing it's value

I'm working on an API that is responsible for managing long running jobs. You create jobs by posting to 

/jobs/

which gives you an object with a progress field like so

{"progress_percentage": 0.0, "id": 1}

You can then make changes to the instance of this job by patching to

/jobs/<job-id>/

While the jobs are running I want to hit the api to increase the progress as the job is running, starting at 0.0, ending at 100.0. Any given job can be split into smaller tasks, these tasks can run concurrently, and can be assigned progress 'chunks'. I want each chunk to increase the progress relative to it's assigned progress. For example if task 1 is running and is assigned a progress chunk of 30% and there is a for loop in this task of size 5, I would want to increase the progress percentage by 6% for each iteration of that for loop, regardless of what the current progress percentage is.

Other jobs may just simply want to set the percentage (not increase it)

My question then is, what would be the most desirable way to do this from an API design point of view.

I see a few options

1.

PATCH /jobs/<job-id>/

with a payload of

{"progress_percentage": {"increase": 6.0}}

to increase

or

{"progress_percentage": {"set": 35.0}}

to set.

2.

POST /jobs/<job-id>/progress_percentage/

with a payload of

{"amount" 6.0} or [6.0]

to increase or

PATCH /jobs/<job-id>/

with a payload of

{"progress_percentage" 30.0}

to set.

Upvotes: 1

Views: 807

Answers (1)

Mo A
Mo A

Reputation: 727

Assuming your REST API is not publicly exposed,I believe option 1 to be more favourable.

As 'progress_percentage' is a property of the 'job' object, I don't see the need to introduce a sub-resource (i.e. /progress_percentage).

Also, if you'd want to execute a PATCH for multiple 'job' attributes, you'd want to be able to do it as part of a single request and payload, rather than triggering multiple PATCH requests. For that, usage of 'PATCH /jobs/{job-id}/' makes sense.

Upvotes: 1

Related Questions