I don’t wanna be pedantic but most things we call REST aren’t REST. The original definition of REST is what we typically call HATEOAS. So when you say JAON API almost always means not REST you need to qualify that.
However you like, REST doesn’t dictate anything there. Just be consistent and use hypermedia.
JSON APIs almost never follow REST because they almost never use JSON as hypertext. Worse, no complete stable hypertext JSON standard exists. There’s JSON-HAL, but it lacks a way to represent resource templates (think HTML’s <form>).
Therefore, with JSON APIs ignoring one of the most basic idea behind REST, why would anyone expect them to follow another idea of REST - consistency?
REST is a deceptively simple concept. Any time you build an HTML website a human can navigate without consulting documentation, you’re doing it better than vast majority of swagger documented corporate APIs.
Fun fact, I actually did implement JSON-HAL and peers wondered why I was putting this “silly _links dictionary member” in there.
I’ll say I’ve seen other REST APIs using json and at least honor the concept of hypermedia, but in a useless way. They’ll have links specified, but even within their API no consistency on what dictionary keys would refer to related resources versus data.
The argument probably goes something like " if you adhere strictly to REST the error codes are all you need" and then metadata can be sent in response headers.
how should a REST API respond to the client sending a URL the ends in a string instead of a numeric ID? like api.social/users/ceeforayteen instead of api.socail/users/11037
I would do a 400 (Bad Request). Then, with varying amounts of detail depending on the scale of the project and the framework capability, the response body would be something like:
{ “error”:true, “reason”: “validation”, “detail”: “user id should be numeric” }
A RESTful service is (usually as of today) a JSON API. They aren’t mutually exclusive things.
There’s no black and white definition there.
However, when someone is creating a RESTful service, they’re stating that they’ll be paying mind to HTTP Verbs and status codes as a fundamental part of their design.
In the original image posted, that dev clearly wasn’t paying mind to the HTTP layer and as such a commenter called it just a “JSON API”, which is the catchall, ugly, Wild West, typical way of doing things (always return 200, errors are in the json).
Once again tho, it’s not black and white. Others can and will disagree and want to be pedantic. I’ve been a professional dev for 35 years, devs love to argue abt this shit.
Devs and standards have a contentious relationship.
If I develop something, I obviously know what works best for me, so I don’t want to be constrained by some dumb standard. If someone else doesn’t follow them and it makes things harder for me, they’re a clueless fuckwit that shouldn’t be allowed near a computer ever again.
Yes, that’s a double standard: I don’t even have a standard when it comes to handling standards.
JSON API almost always means “not REST”. In other words, it works as intended.
I don’t wanna be pedantic but most things we call REST aren’t REST. The original definition of REST is what we typically call HATEOAS. So when you say JAON API almost always means not REST you need to qualify that.
how would you return metadata or more detailed error codes?
However you like, REST doesn’t dictate anything there. Just be consistent and use hypermedia.
JSON APIs almost never follow REST because they almost never use JSON as hypertext. Worse, no complete stable hypertext JSON standard exists. There’s JSON-HAL, but it lacks a way to represent resource templates (think HTML’s
<form>).Therefore, with JSON APIs ignoring one of the most basic idea behind REST, why would anyone expect them to follow another idea of REST - consistency?
REST is a deceptively simple concept. Any time you build an HTML website a human can navigate without consulting documentation, you’re doing it better than vast majority of swagger documented corporate APIs.
Fun fact, I actually did implement JSON-HAL and peers wondered why I was putting this “silly _links dictionary member” in there.
I’ll say I’ve seen other REST APIs using json and at least honor the concept of hypermedia, but in a useless way. They’ll have links specified, but even within their API no consistency on what dictionary keys would refer to related resources versus data.
returning a 400 never prevented me from adding more info to the response
The argument probably goes something like " if you adhere strictly to REST the error codes are all you need" and then metadata can be sent in response headers.
how should a REST API respond to the client sending a URL the ends in a string instead of a numeric ID? like api.social/users/ceeforayteen instead of api.socail/users/11037
I would do a 400 (Bad Request). Then, with varying amounts of detail depending on the scale of the project and the framework capability, the response body would be something like: { “error”:true, “reason”: “validation”, “detail”: “user id should be numeric” }
that’s what i would do too—a JSON response. or is that not what “JSON API” means?
A RESTful service is (usually as of today) a JSON API. They aren’t mutually exclusive things.
There’s no black and white definition there.
However, when someone is creating a RESTful service, they’re stating that they’ll be paying mind to HTTP Verbs and status codes as a fundamental part of their design.
In the original image posted, that dev clearly wasn’t paying mind to the HTTP layer and as such a commenter called it just a “JSON API”, which is the catchall, ugly, Wild West, typical way of doing things (always return 200, errors are in the json).
Once again tho, it’s not black and white. Others can and will disagree and want to be pedantic. I’ve been a professional dev for 35 years, devs love to argue abt this shit.
Devs and standards have a contentious relationship.
If I develop something, I obviously know what works best for me, so I don’t want to be constrained by some dumb standard. If someone else doesn’t follow them and it makes things harder for me, they’re a clueless fuckwit that shouldn’t be allowed near a computer ever again.
Yes, that’s a double standard: I don’t even have a standard when it comes to handling standards.
Tabs vs spaces comes to mind.
Depends on the verb and the application. If the string is valid 200, if it isn’t 400, 404.
It’s still just another type of ID so you can do lookups on it. Nothing would change. UUIDs are used all the time.