211–220 of 238 posts
Earlier quoted context omitted.
I don't think I've ever come across any third party actually implementing HATEOAS ( https://en.wikipedia.org/wiki/HATEOAS )
HATEOAS have always sounded like a delicious part of a healthy breakfast
A few things I see rarely discussed that I often do: - Always use a response envelope - HTTP status is not the same as your application status. I always include a "status" field in the response envelope (OP recommends standardizing errors but I think standardize all of it) - Always have an unique error code for every error your API can return (they should also be URL safe ("some-thing-went-wrong"), basically an enum…
- Always use a response envelope I would mostly agree except in 1 case, streaming data is easier without an envelope. Making some array inside an envelope stream is usually more code and messier than just getting some metadata out of header. So if you have something like data integration endpoints and you expect someone could pull many megs of records, consider no envelope.
I agree, and would go so far as to say streaming data would probably have a different delivery mechanism all together - SSE/websockets/etc. if you were doing long polling I may still want to put the metadata in the body but I agree it could be kept out of sight quite nicely in the headers.
Earlier quoted context omitted.
Such simple approach is limited only to errors without arguments. For more complex use cases, where we would want an error message to indicate that field value was too long and in addition provide maximum field length, we would need to introduce new field in the error response. While it is solvable by adding this information to client application side. It would create a situation where the logic is duplicated in two…
Interesting! Do you find that returning an array of errors works in practice? Most validation I’ve seen looks like: raise error if foo raise other_error if bar This pattern turns into one exception per response, and some foresight in architecting exceptions would be needed
Earlier quoted context omitted.
Interesting! Do you find that returning an array of errors works in practice? Most validation I’ve seen looks like: raise error if foo raise other_error if bar This pattern turns into one exception per response, and some foresight in architecting exceptions would be needed
The Phoenix framework does this for forms. It requires a whole system built around a type called a Changeset that describes input parameters, their validity, and how to modify a struct to reflect the valid changes. In practice this ends up tightly coupled to the database layer for simplity.
Earlier quoted context omitted.
Huh? There’s full browser support for all of those verbs. What is the argument for not supporting them?
The HTTP request APIs pass through any method name you write. The HTML forms only support GET and POST. Try it.
Sometimes, I feel that we ought to have a simple protocol, on top of HTTP, to simply do remote procedure calls and throw out all this HTTP verbs crap. Every request is a http POST, with or without any body and the data transfer is in binary. So that objects can be passed back and forth between client and server. Sure, there is gRPC, but it requires another API specification (the proto files). There I said it. HTTP Ve…
Earlier quoted context omitted.
But those 15 requests are then all occurring over a local network (in the data center), not over the Internet. The true power with GraphQL is that it might not even make all 15 calls because it will entirely depend on what you are querying for. E.g. if you query for a User but not the Orders for that User, then the request to retrieve the orders is simply skipped by GraphQL.
Great point. I have only used Apollo for GraphQL, and I found a few things about it offputting (e.g. I need a 3rd-party library to figure out what fields the client actually requested). What GraphQL server do you use? Or is Apollo + Express generally a good "default" option for basic setups?
Earlier quoted context omitted.
Sometimes timezones or the like change. So for future dates, those textual represations are probably better. Example: in November you create an appointment in 6 months at 15h, but then your government decides, to not use summer time next year. If you use timestamps your appointment will be wrong by one hour (humans tend to keep the 15h). In general, I am a huge fan of timestamps, but I think it is good to know where…
> Sometimes timezones or the like change. Why would you ever want anything to do with timezones in an API? Even for appointments, it's still a timestamp. Timezone should be applied the very last moment, as part of date formatting for output on the client. If you allow your users to create appointments this much in advance and then they miss them, it's a UX problem, not an API design problem.
In the example in the post you’re replying to, the time zone change means the time stamp would be wrong by an hour. This doesn’t mean that people should show up an hour earlier or later than initially intended!
Extra points: document the API / have an API technical writer in the team. Part of a good API design is documenting it. If you use an API specification format, such as OpenAPI, design and documentation overlap nicely.
Ah yes, the classic: POST /document/:id?params Creates a document with parameters
Earlier quoted context omitted.
Localization has entered the chat. You need codes because the field isn't going to be 'email' for much longer than it takes for your management to realize that people outside of the US also have wallets.
My view is that apis should simply return a number when an error occurs. The vendor should supply a list of error codes to its consumers, translated into as many languages as necessary. The developers who are consuming the api can then determine how best to present the error to its end users. A set of error numbers is tied to the version of the api that is being consumed so there should be no surprises.
Is that what you're saying? Or did I misunderstand you?