what's with the PHP hate?
Because if you build your startup's site using PHP, you'll never be able to scale like a Flickr, Digg, Wikipedia, or Facebook.
// Ahem.
RESTful API Server - Doing it right
21–30 of 33 posts
Re: RESTful API Server - Doing it right
#22I realise it's only part 1, but this post doesn't even mention hypermedia. Its advice on documentation says that you should explain how clients construct URIs. Groan. I don't fully understand what it is about HATEOAS that people find difficult or unconvincing. They must use web sites every day. When you want to buy a book at Amazon, do you read their documentation and then construct a URL? No, you go to amazon.com an…
I must admit that the author's description of REST sounds awfully like what I thought REST was before I sat down and tried to design a RESTful API. There was a very distinct moment when I "got" the concept of only requiring a single URL and then navigating the resulting documents - as you say exactly like a web browser (which is, of course, the whole point). It's clearly non-obvious to work with an API primarily as a…
I feel the same way. My first API on my current project was a horrible mess, and did I only realize why it sucked and what I needed to change when I decided to play with Backbone.js over a weekend using my API as a data source. The only way, I think, one can build a RESTful API is to do it from the client's perspective, much like BDD builds software using a list of actions the user wants to make.
If you're not using your own API, then it's probably broken.
Re: RESTful API Server - Doing it right
#23Earlier quoted context omitted.
It's yet another implementation detail that drags the reality of RESTful web service development farther away from the principle that it's easy because it's based on HTTP and we already know HTTP. I'm not writing this to dump on REST. I still think it's the right approach to build a web service over HTTP, but I'm also conscious of the diminishing returns on each incremental step toward pure RESTfulness. I'm just tryi…
Maybe I'm missing something, but why the resistance to returning a "meaningful" content type in a response? It's just a name for the structure you have outlined there.
Two reasons that I can see...
If the server generates custom mimetypes, clients have to ensure they "Accept:" the correct mimetype for every request. And if you have multiple data types (and you will have multiple data types), then this "Accept:" header will vary for every request. Getting this right is an irritant to client developers with no actual benefit to them, and a great potential source of bugs.
Much easier is if the client can just send "Accept: application/json" or "Accept: application/xml" for every request.
If the server generates custom mimetypes, and you update your API to v2 which produces an article listing in an incompatible format, you either have to introduce a version number into your mimetype (which seems messy and pointless busywork), or stick with the same mimetype and accept that your custom mimetypes aren't actually particularly meaningful as their meaning can change substantially over time (so why did you have them in the first place?)
Much easier is if the server had just used "Content-Type: application/json" or "Content-Type: application/xml" which will always be correct.
Re: RESTful API Server - Doing it right
#24Earlier quoted context omitted.
I must admit that the author's description of REST sounds awfully like what I thought REST was before I sat down and tried to design a RESTful API. There was a very distinct moment when I "got" the concept of only requiring a single URL and then navigating the resulting documents - as you say exactly like a web browser (which is, of course, the whole point). It's clearly non-obvious to work with an API primarily as a…
I feel the same way. My first API on my current project was a horrible mess, and did I only realize why it sucked and what I needed to change when I decided to play with Backbone.js over a weekend using my API as a data source. The only way, I think, one can build a RESTful API is to do it from the client's perspective, much like BDD builds software using a list of actions the user wants to make. If you're not using…
I found that manually using my API from the command line using cURL helped a lot (with a bit of cutting and pasting to extract the URLs I want).
Re: RESTful API Server - Doing it right
#25Earlier quoted context omitted.
Maybe I'm missing something, but why the resistance to returning a "meaningful" content type in a response? It's just a name for the structure you have outlined there.
Two reasons that I can see... If the server generates custom mimetypes, clients have to ensure they "Accept:" the correct mimetype for every request. And if you have multiple data types (and you will have multiple data types), then this "Accept:" header will vary for every request. Getting this right is an irritant to client developers with no actual benefit to them, and a great potential source of bugs. Much easier…
If the server generates custom mimetypes, clients have to ensure they "Accept:" the correct mimetype for every request.
No, he doesn't. First, the server can send whatever it wants - nothing breaks if you reply with your custom media type to a generic "application/json" request.
Second, even if you want to be correct, that's what wildcards are for: the client can simply send always the same header:
Accept: application/*+json
I still don't get what's the problem with changing a string. I think you're using a bad framework.
Re: RESTful API Server - Doing it right
#26Earlier quoted context omitted.
Maybe I'm missing something, but why the resistance to returning a "meaningful" content type in a response? It's just a name for the structure you have outlined there.
Two reasons that I can see... If the server generates custom mimetypes, clients have to ensure they "Accept:" the correct mimetype for every request. And if you have multiple data types (and you will have multiple data types), then this "Accept:" header will vary for every request. Getting this right is an irritant to client developers with no actual benefit to them, and a great potential source of bugs. Much easier…
[deleted]
Re: RESTful API Server - Doing it right
#27Earlier quoted context omitted.
Two reasons that I can see... If the server generates custom mimetypes, clients have to ensure they "Accept:" the correct mimetype for every request. And if you have multiple data types (and you will have multiple data types), then this "Accept:" header will vary for every request. Getting this right is an irritant to client developers with no actual benefit to them, and a great potential source of bugs. Much easier…
If the server generates custom mimetypes, clients have to ensure they "Accept:" the correct mimetype for every request. No, he doesn't. First, the server can send whatever it wants - nothing breaks if you reply with your custom media type to a generic "application/json" request. Second, even if you want to be correct, that's what wildcards are for: the client can simply send always the same header: Accept: applicatio…
I doubt that sending a mimetype which the client has said it can't accept would be on anyone's list of best practices.
This is a good point, though, not sure why it escaped me:
Accept: application/*+json
Probably. This isn't why, though.
Re: RESTful API Server - Doing it right
#28Earlier quoted context omitted.
It's yet another implementation detail that drags the reality of RESTful web service development farther away from the principle that it's easy because it's based on HTTP and we already know HTTP. I'm not writing this to dump on REST. I still think it's the right approach to build a web service over HTTP, but I'm also conscious of the diminishing returns on each incremental step toward pure RESTfulness. I'm just tryi…
What trouble? Are you not documenting what you return anyway? What's the cost of just changing the mediatype to some different string? For a client, is it worth the trouble to learn a new content-type to determine what's a hyperlink in my JSON response, when they can just look at the response and see something like the following? Personally, I think that mindset will hold us back. People still think of RESTful servic…
What I'm trying to suggest is that the point at which a schema is powerful and generic enough to work as a general-purpose web service API for an arbitrary use case, it has become more difficult and complicated to learn, configure and use than a much simpler, discoverable ad-hoc schema that closely matches the functionality of your web service.
In general, REST principles give more than they take, which is why I try to follow them; but you're always going to have to find the sweet spot of abstraction that provides the right amount of power and flexibility combined with the right amount of discoverability and predictability.
> What's the cost of just changing the mediatype to some different string?
I'm happy to change a server's content-type from application/json to application/vnd.my-adhoc-service+json, but that won't change the client's need to read my documentation and play with the service before they can figure out how to use it. That's true even if I move the documentation out to an RFC.
One real advantage I can see is to use the media type for versioning, but even that doesn't remove the need for a client to intervene if they want to upgrade their code to work with the newer API version.
So it's not really clear to me that a custom media type is significantly more useful for the client, even if it is more 'proper'. When a constraint feels ceremonial, I become suspicious that it exists to drive purity-for-its-own-sake rather than a real benefit.
Re: RESTful API Server - Doing it right
#29Earlier quoted context omitted.
Maybe I'm missing something, but why the resistance to returning a "meaningful" content type in a response? It's just a name for the structure you have outlined there.
Two reasons that I can see... If the server generates custom mimetypes, clients have to ensure they "Accept:" the correct mimetype for every request. And if you have multiple data types (and you will have multiple data types), then this "Accept:" header will vary for every request. Getting this right is an irritant to client developers with no actual benefit to them, and a great potential source of bugs. Much easier…
So if you don't communicate that the version of the structure of your response has changed through the Content-Type, where would you do it?
Re: RESTful API Server - Doing it right
#30Earlier quoted context omitted.
It's yet another implementation detail that drags the reality of RESTful web service development farther away from the principle that it's easy because it's based on HTTP and we already know HTTP. I'm not writing this to dump on REST. I still think it's the right approach to build a web service over HTTP, but I'm also conscious of the diminishing returns on each incremental step toward pure RESTfulness. I'm just tryi…
Maybe I'm missing something, but why the resistance to returning a "meaningful" content type in a response? It's just a name for the structure you have outlined there.
I'm happy to change a server's content-type from application/json to application/vnd.my-adhoc-service+json, but that won't change the client's need to read my documentation and play with the service before they can figure out how to use it. That's true even if I move the documentation out to an RFC.
One real advantage I can see is to use the media type for versioning, but even that doesn't remove the need for a client to intervene if they want to upgrade their code to work with the newer API version.
So it's not really clear to me that a custom media type is significantly more useful for the client, even if it is more 'proper'. When a constraint feels ceremonial, I become suspicious that it exists to drive purity-for-its-own-sake rather than a real benefit.