299
votes
Accepted
Should the solution be as generic as possible or as specific as possible?
My rule of thumb:
the first time you encounter the problem, only solve the specific problem (this is the YAGNI principle)
the second time you run into the same problem, consider generalizing the ...
- 3,218
296
votes
Accepted
Should you write your back-end as an API?
Yes you should.
It not only makes your back end re-usable but allows for more security and better design. If you write your backend as part of a single system, you're making a monolithic design that'...
- 48k
109
votes
Why do so many standards for JSON API response formats contain a "success" property in the response body instead of just using HTTP status codes?
Many people take HTTP status code as “successful communication with the server”.
Now if a customer wants to buy a US$200 item and has only US$100 in their account, the JSON response will be “failure, ...
- 37.9k
103
votes
Accepted
Should you guard against unexpected values from external APIs?
You should never trust the inputs to your software, regardless of source. Not only validating the types is important, but also ranges of input and the business logic as well. Per a comment, this is ...
- 3,257
102
votes
What should be the http status code for "Service not available in your area" error?
Any HTTP error code would be inappropriate. There is no error or problem of any sort from an HTTP perspective so it should be something in the 200 range. You politely inform some of your users that ...
- 15.5k
99
votes
Accepted
Should I return an HTTP 400 (Bad Request) status if a parameter is syntactically correct, but violates a business rule?
This is a great question, and still highly relevant given the historical context (and seemingly contradictory definitions) of the HTTP return codes. Even among the answers to this question there are ...
- 1,827
99
votes
Accepted
Is there a pattern for handling conflicting function parameters?
Seeing the implementation, it appears to me what you really require here is 3 different functions instead of one:
The original one:
function getPaymentBreakdown(total, startDate, endDate)
The one ...
- 185k
98
votes
Accepted
Should a REST API return a 500 Internal Server Error to indicate that a query references an object that does not exist?
I think a 404 response is the best semantic match here, because the resource you were trying to find (as represented by the URI used for the query) was not found. Returning an error payload in the ...
- 5,956
97
votes
Should the solution be as generic as possible or as specific as possible?
A specific solution [...] requires more work in the future if similar requirement is needed
I have heard this argument several dozen times, and - to my experience - it regularly turns out to be a ...
- 185k
96
votes
Should you write your back-end as an API?
You cannot possibly avoid building an API. Even if you build "just a Website", it will still need to get its data from your backend somehow. However you decide to do this, that is your de facto API.
...
- 2,160
86
votes
RESTFul: state changing actions
I find the practices described here to be helpful:
What about actions that don't fit into the world of CRUD operations?
This is where things can get fuzzy. There are a number of approaches:
...
- 969
86
votes
What should be the http status code for "Service not available in your area" error?
5xx errors are server errors - something went wrong on the server. In particular, a 503 indicates that:
the server is currently unable to handle the request due to a temporary overload or scheduled ...
- 3,342
76
votes
Accepted
How to design a REST API that can "prompt" the client about long-running operations?
For long-running operations, it often helps to model the active job as a REST resource with its own structure and/or sub-resources.
For example, starting a job may return a result such as
202 Accepted
...
- 12.1k
66
votes
Should the solution be as generic as possible or as specific as possible?
TL;DR: it depends on what you're trying to solve.
I've had a similar conversation with my Gramps about this, while we were talking about how Func and Action in C# are awesome. My Gramps is a very old ...
- 2,011
65
votes
Why is Math.Sqrt() a static function?
Suppose we're designing a new language and we want Sqrt to be an instance method. So we look at the double class and begin designing. It obviously has no inputs (other than the instance) and returns ...
- 1,175
63
votes
Should you write your back-end as an API?
I know microservices are all the rage right now, but they aren't always worth it. Yes, loosely coupled code is the goal. But it shouldn't come at the expense of a more painful development cycle.
A ...
- 747
63
votes
Declaring that a function never returns
This is one of those cases where infinite loops are so predominantly a bad idea that there's no real support/convention around using them.
Disclaimer
My experience is with C# (as is your code example, ...
- 37.5k
56
votes
Accepted
Why do so many standards for JSON API response formats contain a "success" property in the response body instead of just using HTTP status codes?
A few potential reasons why you may wish to do this are:
the fact that some HTTP clients treat anything other than 2xx as an "exception" to be thrown, which can hide differences between ...
- 1,197
54
votes
Should I return an HTTP 400 (Bad Request) status if a parameter is syntactically correct, but violates a business rule?
I read the first answer and didn't really agree with it because, at least in my reading, a bad request (400) means, "I can't even handle your request because something is fundamentally wrong." And I ...
- 849
50
votes
Accepted
How to describe an architectural shift that intentionally breaks REST standards?
I am uncertain how to best describe this approach when my recommendation is to continue with the existing technology stack, but implement fundamental shifts in the locations where code belongs.
...
- 30.1k
47
votes
What is an Anti-Corruption layer, and how is it used?
Adapter
When you have incompatible interfaces, that perform similar logic, to adapt one into the other, so that you can use implementations of one with things that expect the other.
Example:
You ...
- 1,277
47
votes
Accepted
Why PATCH method is not idempotent?
A PATCH request can be idempotent, but it isn't required to be. That is the reason it is characterized as non-idempotent.
Whether PATCH can be idempotent or not depends strongly on how the required ...
- 68.1k
46
votes
Accepted
RESTful API: HTTP verbs with shared or specific URLs?
In your latter scheme, you keep verbs in the URLs of your resources. This should be avoided as the HTTP verbs should be used for that purpose. Embrace the underlying protocol instead of ignoring, ...
- 1,335
46
votes
What should be the http status code for "Service not available in your area" error?
Neither of those.
If your API is well-designed, the URL includes the name of the city, e.g.
http://example.com/API/Vienna/HailRide
or
http://example.com/API/HailRide?city=Vienna
since IP ...
- 9,280
45
votes
Accepted
null vs missing key in REST API Response
Consider removing empty or null values.
If a property is optional or has an empty or null value, consider dropping the property from the JSON, unless there's a strong semantic reason for its existence....
- 196k
44
votes
Declaring that a function never returns
This depends on the type system and the language.
Many languages have a type for this, for example never in TypeScript, Nothing in Scala and Kotlin, or Void in Haskell.
C has a _Noreturn function ...
- 97.9k
42
votes
Choose between http 401 and 409
Technically, it depends on the HTTP method that you use. I suggest you use PUT because if you do, this line of argument works fine:
If someone wants to follow another user and they already do follow ...
- 4,333
40
votes
Many small requests vs. few large requests (API Design)
One thing to keep in mind is the expected network latency (i.e. ping time) between your clients and your server. In a high-latency situation with otherwise good bandwidth, many small requests will ...
- 523
40
votes
Accepted
Should Microservices talk to each other?
I would generally advise against having microservices do synchronous communication with each other, the big issue is coupling, it means the services are now coupled to each other, if one of them fails ...
- 555
39
votes
Accepted
Function returning true/false vs. void when succeeding and throwing an exception when failing
Throwing an exception is simply an additional way of making a method return a value. The caller can check for a return value just as easily as catch an exception and check that. Therefore, deciding ...
- 103k
Only top scored, non community-wiki answers of a minimum length are eligible