Increment/decrement API

[dougthor42]

There should be an API to increment or decrement a stored value. Options include:

# subtracting 3 from the current value
/api/v1/math/add?value=-3
/api/v1/add?value=-3
/api/v1/add/-3
/api/v1/math/add/-3
/api/v1/increase?value=-3
/api/v1/decrease?value=3
/api/v1/decrease        # subtracts 1 from current value, do it 3x times

Questions:

1. Should it just be for increment and decrement by 1? Or should users be allowed to send other values?
   • Almost definitely allow arbitrary signed values. Forcing just +/- 1 results in excessive API calls.
2. How about other simple math operations? Multiply (scale), power, etc.?
3. Should there be default values (eg: increase = +1, decrease = -1) or always explicit?
   • I'm leaning towards explicit. "Explicit is better than implicit." - PEP 20
4. The add api is already taken - do I want to replace that? I'd then get:
   • add for adding a signed value to the current value (adding a negative value would subtract, of course)
   • scale for multiplying by a signed value
   • append, post, insert, new, or something else for the default act of sending in a new value
   • power... I don't think that's really useful at all.

[dougthor42]

append, post, insert, new, or something else for the default act of sending in a new value

I was thinking I'd go with post: /api/v1/post, but that leads to the question: "Should the HTTP method be part of the api url?"

According to this site:

URIs should not be used to indicate that a CRUD function is performed. URIs should be used to uniquely identify resources and not any action upon them. HTTP request methods should be used to indicate which CRUD function is performed.

In addition, other sites (here, here) say to use plural nouns, not verbs, for endpoints.

Based on that, I guess I'll use metrics? POST /api/v1/metrics. But then how do I manage the fancy math stuff? As an optional arg in the JSON?

{"metric": "foo.bar",
 "value": 0.1,         // always required? no increment/decrement actions that assume value=1?
 "math": "scale"       // "scale", "add"
 }

Or perhaps as url args? Is this even possible?

POST "/api/v1/metrics?action=scale" --data '{"metric": "foo.bar", "value": 0.1}'

[dougthor42]

Or perhaps as url args? Is this even possible?

Yes, but it seems to be very rarely used, so it's likely not a good idea.

I think just adding the optional math key (or whatever I decide to name it. function? action?) to the JSON payload is the way to go.