7

I am researching before starting to work on an API for a web-service I am building. The goal is to be very quick and easy to adapt and use for other developers but fairly hidden for clients using a collection of Webapps to make calls to the service behind the API.

It is the first time making an API for more than internal use and I am now wondering researching the standards out there if I should follow RESTful recommendations or rather just go (my instinct) with POST Requests and a JSON-body that holds all the necessary information.

My reasoning against using GET / HTTP-Verbs:

  • The service has fairly fine grained Read/Write control for every single User and DB items. So even a simple LIST request has to be checked not only for credentials but has to do a bunch of internal validation procedures to see if the client is allowed to ask this questions for this particular piece of data.
  • easy implementation: while coding I usually am happy to not have to hop between GET Urls and POST or PUT bodies to get my JSON payload over the line. Appending them to the URL if it is a GET request or into the body if it is a POST or a PUT. So it feels less of a hassle to just go with POST. but I see that is very much my personal taste rather than true for everybody - I am just damn lazy ;-)
  • not really a valid point because we use SSL anyhow, but https://stackoverflow.com/questions/198462/is-either-get-or-post-more-secure-than-the-other#1744404 suggests that it at least, in theory, it might be a little more secure to not force too much sensitive stuff into the URL. In particular, if even READ/LIST requests are considered sensitive for a service, it feels at least a little weird to operate within the URL.

my reasoning for using GET / HTTP-Verbs:

  • Compatibility: Standards are great. And RESTful APIs still seem the most common ones. GET can be easily tested or used by clients from a browser (not sure if that is really a plus, but it might turn out as one)
  • RESTful forces me into a fine-grained separation of concerns through not only URL but also the HTTP verbs (GET/POST/PUT etc). Only using POST I could do the same through URL or early JSON parsing.
  • this blogpost explains a bit about the issues, I found very helpful

Are there any other strong reasons for using the full variety of HTTP verbs like for example REST principles would suggest?

I cannot find any API that does not use different HTTP Verbs. So I guess there must be very strong reasons for that. I suspect the reasons mentioned in the blogpost to be the most relevant, but wonder if there is more to it and if there are other solutions than the one proposed there (first POST, then serving a new GETable resource and returning the URL)

note

this question is similar to mine but comes from a slightly different angle: Is it bad to use POST only on an API?

  • 1
    That blog post describes using POST to create a search request - this is OK as you're creating the search request. even a search can be something that is created. Using GET for search is limited so this fits. I wouldn't missinterpret that and bend it into something where it doesn't fit however. – iwayneo Sep 11 '18 at 13:07
  • Aaaah! Thanks for pointing that out! I DID misunderstand that one. This is sth that for my concrete use case actually is very relevant for my usecase. thank you! – gauguerilla Sep 11 '18 at 13:43
  • 1
    This article strikes a nice balance. It notes that, in order to be fully REST compliant, you also need HATEOAS, but that most applications don't need that level of rigor. As usual, do what makes the most sense from your perspective. – Robert Harvey Sep 12 '18 at 15:04
9

"What reasons are there AGAINST using only POST HTTP verb in an API?"

You have answered your own question:

The goal is to be very quick and easy to adapt and use for other developers...

If your goal is for other developers to quickly understand and use your API, then use the standards that most developers would expect. It's as simple as that.

To review your reasons for using POST:

  • I think it would be very strange for a list operation to use POST
  • Your laziness in implementing the API will have a direct cost when other developers begin using it and wonder why every operation requires POST
  • Any hypothetical security risks in using GET are far outweighed by arguments for standards

If you want to experiment with an API that only you will ever use, then feel free to do whatever you wish. But if you want other developers to use it then please save us the frustration and just use the standards.

4

GET requests are supposed to be idempotent if your using them to post date then it will violate this and be unexpected by users of your api.

  • 1
    They are not only idempotent but referentially transparent, which is a much stronger property. PUT is only idempotent. – Jörg W Mittag Sep 11 '18 at 19:51
2

If you want to make things easy for developers using your api, don't worry about the RESTfulness of various verbs.

Publish A Client

  • can you extend on that? do you mean: if they have a client they can just model whatever they need around it or use it as an example / demo ? It will have at least 2 clients published with it (for 2 use cases), though those will be mainly for endusers not for developers. though under the hood they would contain everything that the API does for the use cases we are aware of. – gauguerilla Sep 13 '18 at 7:50
  • 1
    if you publish a client then GET or POST is an implementation detail no-one cares about. If you force the developer to write their own client they need to read you docs to find out whether its GET or POST – Ewan Sep 13 '18 at 8:19

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.