201–210 of 273 posts
The only thing something like gRPC is missing that is very valuable from HTTP REST is having standard error codes corresponding to all the HTTP response codes (2xx, 4xx and 5xx codes)
Most of these best practices forget the hard parts of JSON/REST APIs: - How to handle date and time incl. time zones - JSON has no data type for that - Handling of numbers (JSON only has double, which does not fit most cases) - Defined and parseable error responses (rfc 7807 plus extra fields for details) - Localization - do you send translated texts or just error codes? - How to handle updates? Overwrite every field…
Earlier quoted context omitted.
To continue the payment processor example, if there are 10 different reasons for declining a transaction, how do you propose mapping those onto 4xx codes? Would you just choose 10 at random? Or would you just return, e.g., E_INSUFFICIENT_FUNDS?
I'm not sure anyone would propose you randomly map different 4xx codes to a bunch of different internal server errors. For the one example you provided I would probably use a 500 code, return the relevant message and call it a day. In that case you might also return an additional code if you have some extremely complex logic for handling that error at the client side, but in that case your client might be a little to…
By ignoring existing standards and re-inventing the wheel with custom errors the previous development team made the system harder to maintain & harder to onboard.
I interrupted my reading at 'Accept and respond with JSON' to write this comment, before I skipped over that section and returned to reading the rest. Folks that aren't aware of Webmachine should take a look: https://github.com/webmachine/webmachine The 'Accept' header should determine the response type, but content negotiation is something that few bother to implement. Webmachine does that for you, among other thing…
> Webmachine is an application layer that adds HTTP semantic awareness on top of the excellent bit-pushing and HTTP syntax-management provided by mochiweb, and provides a simple and clean way to connect that to your application's behavior. Great buzzwords, I have no idea what this project actually does.
Zalando has amazing api guidelines - https://opensource.zalando.com/restful-api-guidelines
This has massive implications in real-world systems. Rate limiting adds and order of magnitude complexity to a client system due to the next for delayed, conditional execution. So many APIs do rate limiting and don't bother to add information about why it is happening or for how long the limit applies. I've been working with a name-brand system that limits based both on client application and end user. So, effectively, there can be a 429 because the application as a whole is exhausted, or because a particular user is exhausted. There is no additional information, so the only way to know if the limit has lapsed is to try again. It make it incredibly cumbersome to create reliable consumer applications.
Earlier quoted context omitted.
Send ISO date/time in utc. Send numbers as strings. you should be treating this as hostile in your backend anyways, and checking it. Send both an error code, and a string in simple english, or whatever your most common developer language is. If you care about only updating certain fields, track changes and only send those fields to the backend. These arn't really that hard.
> Send numbers as string [...] Why? Why not send a number as number (double) and treat it as hostile in the backend? I dislike sending numbers as string because I think the different data types exist for a reason.
Earlier quoted context omitted.
> This article doesn't mention linking at all, which is at the heart of REST. Please, just don't do it . Yes, I read the dissertation. It's just not a good idea, it has never given me any practical use whatsoever and has always made dealing with the API more annoying. > Most of it is just standard JSON-over-HTTP stuff that's implemented in a variety of frameworks and libraries. Yes, and we call that REST or RESTful a…
Interesting. I usually find it easier to generate URLs on the server and more convenient to consume APIs that include links to related resources. The other option is munging URLs on the client side, which can be tedious. I'm genuinely curious as to how including links in the response could make an API harder or more annoying to use.
Earlier quoted context omitted.
I'm a programmer, and I know HTTP quite well. I know what HTTP semantics are, and this sentence is still gibberish to me. I'd wager the reason I don't is because I'm not that familiar with the erlang ecosystem, so have no idea what mochiweb is, and don't know what this does differently. Your first sentence was quite condescending, FYI, not sure if it was meant to be.
> Your first sentence was quite condescending, FYI, not sure if it was meant to be. No, it was not and thank you for flagging that. Is it condescending to assume one is not a web developer if they don't know content negotiation? I thought that was Web 101 and pretty much one of the first things you go through when learning about HTTP, but maybe things have changed as of late. I'm sorry spelunker if my message came of…
We know about content negotiation it's probably the `Webmachine` `HTTP semantic awareness` `bit-pushing` `HTTP syntax-management` and `mochiweb` that not many people would know.
I'm not sure if you're purposefully trying to be sarcastic but even your current comment is kinda scathing.