Hey friends! Author (@rbluethl) here. :) I just randomly noticed that my post made it to the front page! Thank you all for your comments.
How to Design Better APIs
221–230 of 238 posts
Re: How to Design Better APIs
#222A good checklist of things to mind when designing APIs. Sometimes you forget the good things.
Thanks for the kind words! Appreciate you reading it.
Re: How to Design Better APIs
#223The error messages could be better yet. The example uses a different code per issue, for instance: "user/email_required". Most integrators will build their UI to highlight the input fields that contain an error. Making them parse the `code` field (or special-case each possible code) is pretty toilsome. // from blog post { "code": "user/email_required", "message": "The parameter [email] is required." } Make it parseab…
Hey thanks for your input. These are great additions!
Re: How to Design Better APIs
#224> 5xx for internal errors (these should be avoided at all costs) An anti pattern I’ve often seen has devs avoiding 5xx errors in bizarre ways. I would change the above to make to have monitoring in place to address 5xx errors. By all means, let your code throw a 500 if things go off the rails.
Author here. I generally agree - IF something goes terribly wrong within the application, a 500 is definitely the way to go. The thing is - these just shouldn't happen that often. Because in that case we're having a bigger problem. :D For example I have never seen Stripe return a HTTP 500 from their API. Thing just works.
Re: How to Design Better APIs
#225While I agree with the most aspects of this very good blog post, there is a minor detail that I would like to note: While pagination is important, there is another possibility of pure size - it is using cursors, like mentioned in the JSONAPI specification[1] (containing many of the hints in the topics' post) and in this blog post[1] [1] https://jsonapi.org/format/#fetching-pagination [2] https://dev.to/jackmarchant/o…
Author here. Thanks for the nice words - I appreciate it. I've read that a couple of times in the comments already. Definitely something worth considering, Stripe does this as well. Thanks for your comment.
Re: How to Design Better APIs
#226For #2, better yet, prefer RFC 3339.
Author here. I read that a couple of times already. RFC 3339 is what you should use - I should probably change that (it's what I actually meant). :) Thanks for pointing that out.
Re: How to Design Better APIs
#227lol this could have been a single line blog post: “Do whatever stripe does with their APIs.” I kid. There’s some good stuff in here.
Author here. Haha! You are right. I admire Stripe's API and there's absolutely a lot of things in it that are my "benchmark" when it comes to good APIs. However, they return UNIX timestamps, for example, which I don't like that much (as stated in the post). They also use POST for updates, because, if I recall correctly, PUT/PATCH wasn't a thing yet when Stripe was built initially. Thanks for the comment.
Re: How to Design Better APIs
#228Earlier quoted context omitted.
> 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.
Why do you say appointments are a time stamp? They are made with humans in mind, people dealing with a local time zone. 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!
Because they are a timestamp. In an overwhelming majority of cases when you're going to deal with time in software, it's a timestamp. Timezones are a client's concern. You ask the user to input the time in their local timezone, then convert that to unixtime and send it to the server.
Timezone isn't a simple constant offset either. For places that use DST, any decent date library would take that into account. If you entered a date in summer while it's winter, it would still result in a correct unixtime.
Re: How to Design Better APIs
#229Earlier quoted context omitted.
Why do you say appointments are a time stamp? They are made with humans in mind, people dealing with a local time zone. 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!
Because they are a timestamp. In an overwhelming majority of cases when you're going to deal with time in software, it's a timestamp. Timezones are a client's concern. You ask the user to input the time in their local timezone, then convert that to unixtime and send it to the server. Timezone isn't a simple constant offset either. For places that use DST, any decent date library would take that into account. If you e…
Do you intentionally just ignore the point made about timezone changes?
Re: How to Design Better APIs
#230Earlier quoted context omitted.
Because they are a timestamp. In an overwhelming majority of cases when you're going to deal with time in software, it's a timestamp. Timezones are a client's concern. You ask the user to input the time in their local timezone, then convert that to unixtime and send it to the server. Timezone isn't a simple constant offset either. For places that use DST, any decent date library would take that into account. If you e…
Do you intentionally just ignore the point made about timezone changes ?
Well, how do operating systems handle this sort of stuff? With updates. When it's at all possible to update. There are many devices that don't receive any updates at all any more. There are some devices that weren't designed to be updatable to begin with.
It's a necessarily manual process and it creates a lot of confusion either way. And it's sufficiently rare to ignore. And these changes tend to be announced in advance.