Why would one prefer ISO 8601 dates over POSIX timestamps?
8601 has a large pattern space - RFC 3339 is a narrower subset of ISO. Somewhere I saw a diagram that convinced me. I link if I can find again.
Edit: a relevant link
How to Design Better APIs
21–30 of 238 posts
Re: How to Design Better APIs
#22Why would one prefer ISO 8601 dates over POSIX timestamps?
* Human readable
* Supports birthdays for people older than 52
* Reliable after 2038
* Supports leap seconds
* HTML date/time spec is a subset
* String collation order matches temporal order
* Excel
Re: How to Design Better APIs
#23Some nice tips in here. However, tip 15, I strongly disagree with: > 15. Allow expanding resources I would suggest the opposite. A REST API should not return nested resources at all. Instead, and to stay with the example provided on the website, to obtain the "orders", the /users/:id/orders endpoint should be called. It might be tempting to return nested resources, because clients would only have to make a single cal…
That's not a rest-y API.
You want
GET /orders?user=Id
Orders can be searched on many dimensions, not inherent to users
Re: How to Design Better APIs
#24Some nice tips in here. However, tip 15, I strongly disagree with: > 15. Allow expanding resources I would suggest the opposite. A REST API should not return nested resources at all. Instead, and to stay with the example provided on the website, to obtain the "orders", the /users/:id/orders endpoint should be called. It might be tempting to return nested resources, because clients would only have to make a single cal…
I've consumed the kinds of APIs you're referencing and they are my least favorite. I would prefer a poorly documented API over one that returns me 15 IDs that I must look up in separate calls. I think there's a reason those APIs also tend to have rate limits that are way too low to be useful.
No post body was provided.
Re: How to Design Better APIs
#25Why would one prefer ISO 8601 dates over POSIX timestamps?
They can include a local timezone. Sometimes there's a big difference between 12am in UTC+0 and 3am in UTC+3 despite representing the same instant in time.
True enough, but I would still recommend that API responses normalize to UTC (Z suffix) in the general case and document as much, and if actually returning a timestamp with a specific timezone, document the intended meaning.
Re: How to Design Better APIs
#26We don't use PATCH but use a PUT for partial objects. We have validator code at every endpoint and we validate both creates and updates. When a PUT comes in, the validator knows what can and can't be changed. Depending on your role, the validator lets you change certain things can be updated as well. A PATCH would need these too and now you have more code to deal with. Also, it requires the developer to now worry that they have all the fields for a complete object or not.
Re: How to Design Better APIs
#27Mostly common-sense things, but I can't wait for the community to stop trying to use PUT, PATCH, DELETE and the like. There's a reason that in 2022 web forms only support GET and POST (and implicitly, HEAD).
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.
Re: How to Design Better APIs
#28Earlier quoted context omitted.
I've consumed the kinds of APIs you're referencing and they are my least favorite. I would prefer a poorly documented API over one that returns me 15 IDs that I must look up in separate calls. I think there's a reason those APIs also tend to have rate limits that are way too low to be useful.
Quoted post unavailable.
I would rather you not assigning hate to the entirety of autistic developers. There are plenty of autistic developers who are fully capable of designing great APIs with awesome usability. Being autistic has nothing to do with how APIs are developed.
Re: How to Design Better APIs
#29I’m gonna say it:
Many rest apis are lazy and developer friendly, not consumer friendly.
If you have related resources, let’s say, product and product options as two distinct endpoints:
- /api/product
- /api/options
Then, and I want to be clear here, it is impossible for a client to perform an atomic operation on multiple distinct objects types.
Let’s say the client needs to add a product with a single option or fail.
You can create a product.
You can create an option.
You can add an option to a product.
…but, at some point in time, a product will exist with no options on it.
This kind of “pure” rest api is simply convenient to the developer because they push the problem of object consistency to the client.
…but that’s not a client concern.
If a product needs to be associated with an option on creation, then your api should offer that as an endpoint.
It doesn’t meet the “standard” for a rest api?
Too bad.
Write APIs that do what the customer / consumer needs not lazy APIs that just make your life easier.
I’ve worked with a lot of APIs and you know what I do not give the tiniest moment of care about?
Consistency.
I do. Not. Care. If POST /api/foo creates an object, or if the endpoint is /api/foo/create.
Messy? Inconsistent?
I don’t care. Just put it in the documentation and I’ll find it and use it.
…but if your api forces object relational consistency onto me as an api consumer, you have no idea how much pain and hassle you’ve caused me having to implement my own set of fake transactions over your stupid api.
Please, write APIs for consumers, not according to “the rules” of rest APIs.
…and provide documentation. :)
Re: How to Design Better APIs
#30We don't use PATCH but use a PUT for partial objects. We have validator code at every endpoint and we validate both creates and updates. When a PUT comes in, the validator knows what can and can't be changed. Depending on your role, the validator lets you change certain things can be updated as well. A PATCH would need these too and now you have more code to deal with. Also, it requires the developer to now worry tha…
Based on that description, you may be using PUT in conflict with its semantics (namely, idempotent way to replace an entire resource).
This is one reason why I don't bother with these methods and stick to GET and POST.