HN Explorer

Ask HN: Counter-arguments: Why should we go for a RESTful API?

1 points by Nilef ↗ HN
I've been working on an API design in my current role for a while now, and for various reasons the delivery team are looking to cut down the workload.

Our business carries out work on behalf of clients (White labelled trade) - So we have an API where our clients can create a Customer Resource, provide a Quote for that Customer, Provide an actual proposal of work for that customer, and then schedule the work in.

I propose that Customers, Quotes and Proposals are our Resources

However, the delivery team argues that, as this is not an open API (It is for several partners right now but could rise to 1000+), we can simply go with things like /v1/SubmitProposal and /v1/RetrieveProposal rather than carry out all the separate REST operations, because as long as our clients can create business, what else do they really need? They have their own databases to save data in etc.

I'm struggling to articulate business benefits to going for a full REST API vs. functions specified in a REST-looking format. What are the advantages/disadvantages that I am missing?

4 comments

[ 3.4 ms ] story [ 18.7 ms ] thread
slackingoff2017
If it isn't an open API it doesn't really matter. I would use gRPC (protobufs) so you get easy binding on both sides and better efficiency.

If third parties will need to use the API at any point I would use REST and follow Google's API design guidelines.

al2o3cr 

    However, the delivery team argues that, as this is not an open API (It is for several partners right now but could rise to 1000+)
The only difference between an "open API" and one with 1000 partners is that the second one won't show you the documentation until after you've already paid. That's a garbage reason to make bad software.

    rather than carry out all the separate REST operations
Not sure I'm following what you mean here. There's nothing wrong with having a complex payload (customer + quote + proposal) if that's a meaningful operation for your domain.
davelnewton
If you don't need a "full" REST API (whatever that means) then there is no business benefit to a "full" REST API.

And be honest: the back end for handling either is the same. No reason the same code can't be used if/when you need `v2/proposals` with RESTful verbs.

The biggest benefit for "full" REST is that lots of tooling supports it and it might cut down on documentation time.

brudgers
Business benefits and deficits are best measured financially. A technology decision in an area without direct or indirect financial benefits and deficits is not a business decision, though it may be an interesting argument for philosophical or other reasons.

As presented, the argument for the status quo is centered around customers/clients/partners rather than a technical architecture. That seems decidedly more of a business case.

Good luck.