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 ...
user avatar
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'...
user avatar
  • 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, ...
user avatar
  • 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 ...
user avatar
  • 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 ...
user avatar
  • 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 ...
user avatar
  • 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 ...
user avatar
  • 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 ...
user avatar
  • 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 ...
user avatar
  • 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. ...
user avatar
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: ...
user avatar
  • 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 ...
user avatar
  • 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 ...
user avatar
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 ...
user avatar
  • 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 ...
user avatar
  • 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 ...
user avatar
  • 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, ...
user avatar
  • 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 ...
user avatar
  • 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 ...
user avatar
  • 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. ...
user avatar
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 ...
user avatar
  • 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 ...
user avatar
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, ...
user avatar
  • 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 ...
user avatar
  • 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....
user avatar
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 ...
user avatar
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 ...
user avatar
  • 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 ...
user avatar
  • 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 ...
user avatar
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 ...
user avatar

Only top scored, non community-wiki answers of a minimum length are eligible