Why are Stack Exchange API methods named like this

Question

I'm curious about https://api.stackexchange.com/docs . I looked up and studied the naming convention to make a REST api. I've seen that in the naming convention, don't use verbs and in the case of the http method, don't put them in the URI.

However, if you look at the code below, you can see that the delete of the http method is in the URI. Is there a reason why they did this?
comments/{id}/delete

Also, if you look at the code below, is there a reason why the verb add was used at the end?
/posts/{id}/comments/add
As far as I'm concerned, since the http method POST is used, I think it's better to delete the add or use it as an addition.

Additional questions, is there a reason why POST is used as the http method instead of deleting it on the answers/{id}/upvote/undo.

I'm not sure if it's right to leave this question here, but I'm leaving a question. You might think it's a silly question, but I'd really appreciate it if you could answer it.

Answer 1

I would argue the Stack Exchange API does a pretty decent job to adhere to the fundamental aspects of a REST API. Do note that REST and RESTful is an architectural style, there is no solid ground / normative specification for this style. Let's list the Representational state transfer constraints from Wikipedia and see if the Stack Exchange API matches.

• Client–server architecture
  Yes, it ticks this box
• Statelessness
  Yes, it ticks this box
• Cacheability
  Yes, it ticks this box
• Layered system
  Yes, it ticks this box (although we don't have insight in the code base we've some background on the overall architecture and bugs)
• Code on demand (optional)
  No, this isn't used but it's optional, so we're still good.
• Uniform interface
  Not 100%, let's have a look at the subitems
  • Resource identification in requests
    Yes, we do that
  • Resource manipulation through representations
    Here is a design decision made to only use GET and POST verbs
  • Self-descriptive messages
    Kind of, but as all responses are JSON this doesn't rely apply.
  • Hypermedia as the engine of application state (HATEOAS)
    Yes, it ticks this box

As you correctly analyzed the Resource manipulation through representations is the one where a huge deviation from the constraints is made. I haven't been present at the design meeting by the coffee machine so I can only speculate a bit. Going over the API I can see places where using the DELETE or PUT verb could have made sense. On the other hand GET and POST are verbs that any client side library will do right of the bat. To make the same URL do a DELETE requires effort by fiddling with an extra parameter. Just posting to a new URL is obvious. On the implementation side of things similar concerns are at play.

On top of that there might be a security related issue as well. I assume the HA-Proxy only allows GET and POST request to minimize the attack surface. Having to do and extra config to allow a wider set of verbs can pose a security risk later on.

So far it looks like there are some decent reasons to have the API designed as is. For what it is worth, I often look at this specific API when I am designing one myself. I can only do a worse job.

Finally there maturity models as well for REST API's. I've looked at the Richardson Maturity Model and this API is easily reaching level 3 and there is no level 4.

In A Maturity Model for Semantic RESTful Web APIs the authors Ivan Salvadori and Frank Siqueira state:

Classifying the maturity level of a given WEB API is a subjective action. Each client application has different needs that are fitted by a set of features. As a result, [it] is difficult to find a final number that represents the maturity level. It is up to client applications [to] determine which characteristics are more relevant to achieve its goal.

That last sentence is important. Although the Stack Exchange Android and iOS apps are long gone now, during its lifetime it heavily relied on the Stack API and some improvements in the API were certainly driven by feature demands from at least that client app.

Given the many applications and userscripts that use the API today and how most development stacks offer HTTP libraries with GET and POST as its default operations I will say the API strikes a good balance between usability and REST compliance. There is little to no benefit to revisit historical choices to fix things that are not fundamentally broken.

This is fine.