should POST /key be PUT?

[cyphar]

Arguably, POST /key is not an entirely correct use of POST -- since the insertion operation (after #1 gets fixed) is idempotent arguably it should be PUT. However, I'm not sure whether this will confuse students (then again, they'll have to deal with PUT when they move on to "real-world" APIs anyway).

[kennib]

PUT is definitely valid. POST is also valid but way less specific about the nature of the API. I think we could easily have both methods as long as there was a short explanation in the docs.