RE: [coldbox:12465] General Questions - API related

2) Yes, I already am using ColdBox for this. The question is, if a particular operation does not support POST or PUT, but only GET and the API call sends in a POST method, should the API throw an error (“Method not supported”) or silently fall back to GET anyways…

I say do whatever helps you sleep at night :slight_smile: I saw the reply you got on the Railo list about being as flexible as possible with your inputs and restrictive as possible with your outputs. That being said, if a method only accepts GET now and later you enhance it to accept POST, that could have consequences for a user of your API who had unwittingly beeing using POST all along and now his calls to the API were doing something unexepcted (and possible detrimental). If it were me, I’d lock it down “on account of because” since strictly speaking-- the HTTP method does/should make a big difference in a REST API.



The two biggest things, in my opinion, about APIs is that they should
be consistent and documented. If you think that something should be a
POST, not a GET, then make it a POST and document it as such. If
people are annoyed because they try to use a GET and were confused
that it didn't work, you can then point to the documentation and
explain that it is a POST as specified in the documentation.

The other big thing to think about is how you'll version the API.
Almost without exception, you'll start with an API that fits your
current needs. And then someone will want something else or you'll
come up with a better way to do something. One approach to solving
that problem is to start adding more "optional" parameters that
somehow invoke some different logic and mess with the return some,
etc. Going down that road gets you a mess of an API after a couple of
iterations. Instead, I'd suggest planning for versioning of the API
from the get go. If you need to change how the API behaves, plan a new
version that is tight, consistent and documented and give the
customers that need it access to that API version. Keep track of who
uses the old versions and make a plan for gradually moving them off
and deprecating versions to keep the code base manageable and reduce
customer service headaches. It isn't really rocket science, but it
does require some planning and, more than anything else, consistent
management of the development, deployment and customer service



Thanks for your input Judah, I was planning on versioning an documenting it from the start. And ColdBox Relax is a great tool for documenting/testing the API

Agreed! Should restrict the methods sooner rather than later.

Once again, thanks :slight_smile: