3 ms·

I did this when I first started writing REST APIs. It felt natural and the "right" way to do it. However, it didn't scale well. And I'm not talking about websi

I did this when I first started writing REST APIs. It felt natural and the "right" way to do it. However, it didn't scale well. And I'm not talking about website scalability with traffic. It eventually made development more difficult than it was worth. For example, doing things like enabling/disabling an object is a whole API call rather than a simple UPDATE statement. Either you have to set up an API endpoint to handle toggling the status of that object, or you have to send a whole (sparse) request just to flip a flag. Stuff like that can be tedious. I love REST APIs and I loved what they have done for the web, but I've changed my mind over the last few months that this separation of design is always necessary.

mason55 13y ago
The other mistake that I've seen people make is to try to build their application completely on top of a public API. Sometimes you want to do things in your application that, either for security or scaling reasons, you don't want someone consuming the public API to be able to do (bulk operations, administrative functions, cross-account updates, etc). You either need private API functions or you need to allow actions that aren't triggered by an API call.
- jqueryin 13y ago
  I didn't discuss this in the article, but I should note we do indeed have a fully private API that functions independent of the other and is utilized by our administrative management tools.
- johns 13y ago
  Our public API is a front end for our other services with auth added on and better guarantees against breaking. We don't depend on it directly for anything public facing and I wouldn't suggest anyone completely rely the same API they offer partners/openly to avoid getting into a tough spot with managing changes.
jqueryin 13y ago
You're 100% correct that it's not the absolute quickest or easiest method for implementing what would be deemed a quick change. It is, however, a great way to reduce risk. It's my personal opinion that something even as simple as an UPDATE statement comes at a great cost on your production environment. It should be tested all the way up the chain of environments, backups should be issued on your database, etc, etc. It's really not easy unless you're whole-heartedly okay with the potential ramifications of "cowboy coding" so to speak. I myself have been bitten by performing live query UPDATEs/DELETEs very early on in my career, and API first development is designed to protect people like myself from bad things happening.
debaserab2 13y ago
Yes, separating this logic is tedious, but it's core to the concept and it scales just fine. If every time you want to enable/disable an object you simply write an SQL update query, if you ever want to add any other requirement when an enable/disable occurs (example: you want to record the reason why an object is enabled/disabled) you've now cornered yourself into a situation where you need to identify all the code where you've written the SQL update query. A RESTful API makes a lot of sense when dealing with plain data, but starts making less sense when you're attempting handle full fledged use cases. However, your core API logic should be separated from whatever network layer exposure you're giving your API (and ideally should handle endpoint negotiation for you)
danenania 13y ago
A thin layer that maps methods to api requests should take care of this issue and be simple to write. This is exactly what database drivers and service sdk libs do, abstracting connection details into an easily consumable interface.

mason55 13y ago

The other mistake that I've seen people make is to try to build their application completely on top of a public API. Sometimes you want to do things in your application that, either for security or scaling reasons, you don't want someone consuming the public API to be able to do (bulk operations, administrative functions, cross-account updates, etc). You either need private API functions or you need to allow actions that aren't triggered by an API call.

jqueryin 13y ago
I didn't discuss this in the article, but I should note we do indeed have a fully private API that functions independent of the other and is utilized by our administrative management tools.
johns 13y ago
Our public API is a front end for our other services with auth added on and better guarantees against breaking. We don't depend on it directly for anything public facing and I wouldn't suggest anyone completely rely the same API they offer partners/openly to avoid getting into a tough spot with managing changes.

jqueryin 13y ago

You're 100% correct that it's not the absolute quickest or easiest method for implementing what would be deemed a quick change. It is, however, a great way to reduce risk. It's my personal opinion that something even as simple as an UPDATE statement comes at a great cost on your production environment. It should be tested all the way up the chain of environments, backups should be issued on your database, etc, etc. It's really not easy unless you're whole-heartedly okay with the potential ramifications of "cowboy coding" so to speak. I myself have been bitten by performing live query UPDATEs/DELETEs very early on in my career, and API first development is designed to protect people like myself from bad things happening.

debaserab2 13y ago

Yes, separating this logic is tedious, but it's core to the concept and it scales just fine. If every time you want to enable/disable an object you simply write an SQL update query, if you ever want to add any other requirement when an enable/disable occurs (example: you want to record the reason why an object is enabled/disabled) you've now cornered yourself into a situation where you need to identify all the code where you've written the SQL update query. A RESTful API makes a lot of sense when dealing with plain data, but starts making less sense when you're attempting handle full fledged use cases. However, your core API logic should be separated from whatever network layer exposure you're giving your API (and ideally should handle endpoint negotiation for you)

danenania 13y ago

A thin layer that maps methods to api requests should take care of this issue and be simple to write. This is exactly what database drivers and service sdk libs do, abstracting connection details into an easily consumable interface.