4 ms·

Vendor mimetypes are bad. They defeat the purpose of REST. I should be able to request from Github the content-type(s) I am willing to accept, and Github serve

Vendor mimetypes are bad. They defeat the purpose of REST. I should be able to request from Github the content-type(s) I am willing to accept, and Github serves them to me. It's ironic that a blog post about people understanding REST highlights their misunderstanding of it. What Github does isn't bad, but you shouldn't praise it for being RESTful.

ddagradi 15y ago
This is not about requesting the content type though, it's about requesting the format of the content. If I make a request to https://api.github.com/users/dominic/gists https://api.github.com/users/dominic/gists, I'm getting back JSON, since that's all Github's API supports. Github's custom mime types allow you to request the content of the response in a specific format. In their case, either in Github Flavored Markdown, text, html, or all of the above. They allow you to do this with an Accept header, but the same could be accomplished with a GET parameter tacked onto the request (but that's not RESTful at all!). Using HTTP headers appropriately feels like exactly the right way to handle this situation.
masklinn 15y ago
> Vendor mimetypes are bad. They defeat the purpose of REST. No they don't. Most standard mimetypes are far too broad and completely useless as an actual content type. "application/json" for instance does not tell you anything about the content you're getting, apart from the meta-format in which that content is expressed. Useless.
- KevBurnsJr 15y ago
  It tells you it's not HTML. That's useful if you hope to parse the message body.
  - reinhardt 15y ago
    Ok, so you can "parse" it, which is just a way of saying you can transform a bunch of bytes to a nested structure consisting of a few basic types (dicts, lists, strings, floats, etc). Now what? What can you (or actually your program, not you as a human) do with it without some sort of schema, explicit or implicit?
    - jcrites 15y ago
      Nothing. Exactly! REST is not for machine-driven interactions. It's for humans browsing websites.
      - masklinn 15y ago
        Uh... no.
        j-g-faustus 15y ago
        The REST interface is designed to be efficient for large- grain hypermedia data transfer, optimizing for the common case of the Web, but resulting in an interface that is not optimal for other forms of architectural interaction. http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1 http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch... (Section 5.1.5) When a link is selected, information needs to be moved from the location where it is stored to the location where it will be used by, in most cases, a human reader. http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_2 http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch... (Section 5.2.1) It certainly sounds like "human browsing" was the primary use case. Unless I missed something?
        icebraining 15y ago
        Yes, it's obviously the primary use case, since REST is modeled after HTTP. But the keyword is primary - it doesn't mean it can't or shouldn't be used for machine-driven workflows.
- jcrites 15y ago
  > No they don't I'm pretty sure they do. Vendor mimetypes violate the Uniform Interface constraint and the "no prior knowledge" constraint.
  - masklinn 15y ago
    > Vendor mimetypes violate the Uniform Interface constraint Nope. > and the "no prior knowledge" constraint. Only if you read no further than "no prior knowledge" and made up what it's supposed to mean on the spot. Here's what "no prior knowledge" is: > A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience (i.e., expected to be understood by any client that might use the API). (http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...) Vendor content types are the media types he's talking about. And according to fielding pretty much all of a REST service specification is spent defining media types: > A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state, or in defining extended relation names and/or hypertext-enabled mark-up for existing standard media types. Any effort spent describing what methods to use on what URIs of interest should be entirely defined within the scope of the processing rules for a media type (and, in most cases, already defined by existing media types).

ddagradi 15y ago

This is not about requesting the content type though, it's about requesting the format of the content. If I make a request to https://api.github.com/users/dominic/gists https://api.github.com/users/dominic/gists, I'm getting back JSON, since that's all Github's API supports. Github's custom mime types allow you to request the content of the response in a specific format. In their case, either in Github Flavored Markdown, text, html, or all of the above. They allow you to do this with an Accept header, but the same could be accomplished with a GET parameter tacked onto the request (but that's not RESTful at all!). Using HTTP headers appropriately feels like exactly the right way to handle this situation.

masklinn 15y ago

> Vendor mimetypes are bad. They defeat the purpose of REST. No they don't. Most standard mimetypes are far too broad and completely useless as an actual content type. "application/json" for instance does not tell you anything about the content you're getting, apart from the meta-format in which that content is expressed. Useless.

KevBurnsJr 15y ago
It tells you it's not HTML. That's useful if you hope to parse the message body.
- reinhardt 15y ago
  Ok, so you can "parse" it, which is just a way of saying you can transform a bunch of bytes to a nested structure consisting of a few basic types (dicts, lists, strings, floats, etc). Now what? What can you (or actually your program, not you as a human) do with it without some sort of schema, explicit or implicit?
  - jcrites 15y ago
    Nothing. Exactly! REST is not for machine-driven interactions. It's for humans browsing websites.
    - masklinn 15y ago
      Uh... no.
      - j-g-faustus 15y ago
        The REST interface is designed to be efficient for large- grain hypermedia data transfer, optimizing for the common case of the Web, but resulting in an interface that is not optimal for other forms of architectural interaction. http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1 http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch... (Section 5.1.5) When a link is selected, information needs to be moved from the location where it is stored to the location where it will be used by, in most cases, a human reader. http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_2 http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch... (Section 5.2.1) It certainly sounds like "human browsing" was the primary use case. Unless I missed something?
        icebraining 15y ago
        Yes, it's obviously the primary use case, since REST is modeled after HTTP. But the keyword is primary - it doesn't mean it can't or shouldn't be used for machine-driven workflows.
jcrites 15y ago
> No they don't I'm pretty sure they do. Vendor mimetypes violate the Uniform Interface constraint and the "no prior knowledge" constraint.
- masklinn 15y ago
  > Vendor mimetypes violate the Uniform Interface constraint Nope. > and the "no prior knowledge" constraint. Only if you read no further than "no prior knowledge" and made up what it's supposed to mean on the spot. Here's what "no prior knowledge" is: > A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience (i.e., expected to be understood by any client that might use the API). (http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...) Vendor content types are the media types he's talking about. And according to fielding pretty much all of a REST service specification is spent defining media types: > A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state, or in defining extended relation names and/or hypertext-enabled mark-up for existing standard media types. Any effort spent describing what methods to use on what URIs of interest should be entirely defined within the scope of the processing rules for a media type (and, in most cases, already defined by existing media types).