3 ms·

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

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.

icebraining 15y ago
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. Is RSS difficult and complicated to learn and use? Now think what a pain it would be to develop a feed reader if each blog had its own "simpler" ad-hoc schema. Standards don't have to be complicated, especially if they use an extensible encoding like JSON or XML so that instead of having the kitchen sink they can remain simple and be extended for specific purposes if really needed, without affecting generic clients. 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. The end goal is for different services to agree on standard formats for common resources. Using custom mimetypes is a step in the right direction because it decouples the format recognition and parsing from the service-specific code - it allows clients to use more modular code that works across different services with plenty of reusable code. Is it terribly important? No. But since the costs are essentially none - changing a couple of strings here and there - not doing it seems unreasonable to me. You asked why, I ask why not?
- RyanMcGreal 15y ago
  First of all, I want to thank you for your thoughtful, clearly-articulated comments. Frankly, you've done a better job of explaining and defending dedicated media types than anything else I've seen and I appreciate you taking the time to engage my comments with seriousness rather than condescension. > Is RSS difficult and complicated to learn and use? No, but RSS is a schema with a specific, narrowly defined purpose: to syndicate article-based web pages (and even so, there are 5 or 6 different versions, not including Atom - though your point stands and I don't want to get sidetracked over a quibble). A more apt comparator may be WSDL, which theoretically allows a SOAP web service's remote procedure calls to be discovered programmatically but in practice is such a messy, complicated, leaky abstraction that it's often easier just to build XML templates manually and POST them to the endpoint. I'd be happy to use and support some kind of lightweight schema for JSON that puts URLs in predictable places in the response object and still allows flexibility to provide the functionality a given service needs. I'm not aware of anything that fits this description, but I'm certainly open to it if you have any recommendations. > You asked why, I ask why not? The model of HTTP resources and methods is useful: it unambiguously delivers real, tangible benefits to the developer and the client over ad-hoc protocols riding on top of HTTP like `GET /create_user.php`. Similarly, it makes sense to use the HTTP status codes we already have instead of reinventing your own arbitrary set of status codes and, e.g. sticking them somewhere in the response body. If someone e.g. does a POST request on /users/1337 to create a user, it makes sense to return a 405 status. (However, I tend to put status codes in the response headers and the response body, just to make it easier for clients to notice what's going on.) It also makes sense to put URLs inside the response body in an obvious way so that the client can "click through" to subsidiary resources in a manner analogous to how web pages do it. Again, it makes the web service more or less self-documenting to the client, especially if it uses URLs and HTTP Methods in a sane, predictable way. I'm struggling to understand the benefit of a custom media type beyond merely satisfying one of Roy Fielding's constraints. If the only reason to use a custom media type is to satisfy a constraint, the constraint might be more ceremonial than useful. If two web services are identical except one serves `Content-Type: application/vnd.some-arbitrary-format+json` and the other serves `Content-Type: application/json`, I get suspicious about the benefits of REST when people say the latter is doing it wrong and doesn't deserve to be called RESTful.

icebraining 15y ago

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. Is RSS difficult and complicated to learn and use? Now think what a pain it would be to develop a feed reader if each blog had its own "simpler" ad-hoc schema. Standards don't have to be complicated, especially if they use an extensible encoding like JSON or XML so that instead of having the kitchen sink they can remain simple and be extended for specific purposes if really needed, without affecting generic clients. 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. The end goal is for different services to agree on standard formats for common resources. Using custom mimetypes is a step in the right direction because it decouples the format recognition and parsing from the service-specific code - it allows clients to use more modular code that works across different services with plenty of reusable code. Is it terribly important? No. But since the costs are essentially none - changing a couple of strings here and there - not doing it seems unreasonable to me. You asked why, I ask why not?

RyanMcGreal 15y ago
First of all, I want to thank you for your thoughtful, clearly-articulated comments. Frankly, you've done a better job of explaining and defending dedicated media types than anything else I've seen and I appreciate you taking the time to engage my comments with seriousness rather than condescension. > Is RSS difficult and complicated to learn and use? No, but RSS is a schema with a specific, narrowly defined purpose: to syndicate article-based web pages (and even so, there are 5 or 6 different versions, not including Atom - though your point stands and I don't want to get sidetracked over a quibble). A more apt comparator may be WSDL, which theoretically allows a SOAP web service's remote procedure calls to be discovered programmatically but in practice is such a messy, complicated, leaky abstraction that it's often easier just to build XML templates manually and POST them to the endpoint. I'd be happy to use and support some kind of lightweight schema for JSON that puts URLs in predictable places in the response object and still allows flexibility to provide the functionality a given service needs. I'm not aware of anything that fits this description, but I'm certainly open to it if you have any recommendations. > You asked why, I ask why not? The model of HTTP resources and methods is useful: it unambiguously delivers real, tangible benefits to the developer and the client over ad-hoc protocols riding on top of HTTP like `GET /create_user.php`. Similarly, it makes sense to use the HTTP status codes we already have instead of reinventing your own arbitrary set of status codes and, e.g. sticking them somewhere in the response body. If someone e.g. does a POST request on /users/1337 to create a user, it makes sense to return a 405 status. (However, I tend to put status codes in the response headers and the response body, just to make it easier for clients to notice what's going on.) It also makes sense to put URLs inside the response body in an obvious way so that the client can "click through" to subsidiary resources in a manner analogous to how web pages do it. Again, it makes the web service more or less self-documenting to the client, especially if it uses URLs and HTTP Methods in a sane, predictable way. I'm struggling to understand the benefit of a custom media type beyond merely satisfying one of Roy Fielding's constraints. If the only reason to use a custom media type is to satisfy a constraint, the constraint might be more ceremonial than useful. If two web services are identical except one serves `Content-Type: application/vnd.some-arbitrary-format+json` and the other serves `Content-Type: application/json`, I get suspicious about the benefits of REST when people say the latter is doing it wrong and doesn't deserve to be called RESTful.