6 ms·

Looks like an RPC-style API with multiple endpoints + custom authentication scheme.

by lvillani 15y ago

vyrotek 15y ago
I was going to mention this. If this documentation completely removed the word 'REST' would we have cringed as bad?
- Torn 15y ago
  Probably not, but after seeing how nice REST API's can be with sensible url mappings, HATEOAS, HTTP methods as verbs, etc. it's almost insulting for sharefile to call it RESTful (presumably because it can return JSON?). Off the top of my head: - API method urls are all the same .aspx, regardless of method used - All calls are sent as GET (ignoring the whole point of HTTP methods in REST) - No HTTP method codes as responses for automated parsing - Custom authentication putting credentials in URL or in headers instead of relying on proven HTTP auth schemes we've been using for years (basic, form, etc) - Return format is done with get arguments instead of HTTP content negotiation in headers (not so bad) They've completely missed the boat here.
  - euroclydon 15y ago
    The query string and headers ARE encrypted in https. And forms auth, that's just a post and a cookie. You can't require API clients to support cookies.
    - padobson 15y ago
      But, and excuse me if I'm wrong on this I'm looking for clarification, you should be forcing API clients to sign their requests with some sort of token - which might as well be a cookie. The difference being that a browser keeps track of the cookies for you, and any other client will have to keep track of any auth info itself (in a sqlite DB, xml file, held in memory, etc)
      - euroclydon 15y ago
        It's been a while since I've used AWS, but I consider their API to be the gold standard. IIRC, they have you concatenate a few fields plus a message length, and sign it with your secret key, and this signature is your authentication and anti-tamper mechanism.
      - csears 15y ago
        > sign their requests with some sort of token - which might as well be a cookie Using a token to sign requests is certainly a good idea, but you probably don't want to pass the token around using a cookie, even over HTTPS. Many browsers don't enforce good cookie security and will transmit cookies in the clear if an attacker can redirect the browser to a non-HTTPS URL on the same domain.
  - panzerboy 15y ago
    Can you give an example of a nice REST API? I might have to create one soon and I need some inspiration. Thanks!
    - glassx 15y ago
      Maybe AtomPub? It respects HTTP methods, uses URIs to represent resources correctly, uses <links> to be discoverable (hypermedia), is self-descriptive, is stateful... It uses Atom/XML instead of JSON, but still... (but please correct me if it isn't a good example)
  - arethuza 15y ago
    "API method urls are all the same .aspx, regardless of method used" Isn't it more the fact that they spend all of their efforts documenting the URI structure and very little on the media types used - which is very unRESTful.
  - randomdata 15y ago
    I'm with you on just knowing we can do so much better. Some of the RESTful HATEOS based APIs coming out are simply beautiful. However, - API method urls are all the same .aspx, regardless of method used Extensions are meaningless. That is why we have Accept/Content-type headers. The HTTP spec even explicitly says to not use extensions to relay content information between client and server, from what I recall. - All calls are sent as GET (ignoring the whole point of HTTP methods in REST) I haven't read Fielding's dissertation in a while, but using the "Coles Notes" version from Wikipedia, I do not actually see using the verbs a requirement for REST. I do not recall REST even requiring HTTP. You can use any protocol you want, so long as it conforms to the principles. RESTful, on the other hand, does specify the use of HTTP verbs, but the site in question makes no mention of being RESTful. By not using the proper verbs, the site does appear to violate the caching rules of REST though, I'll give you that. - Custom authentication putting credentials in URL or in headers (neither of which are encrypted over https) The entire https payload is encrypted, headers and all. REST says nothing about how authentication should be implemented. - Return format is done with get arguments instead of HTTP content negotiation in headers (not so bad) This falls under the same as using extensions. Though I will agree with you that it is a reasonable compromise in some cases, such as using a browser where you can't reasonably set your own headers.
- lvillani 15y ago
  I believe it's important to keep things honest. If an API is nowhere near the definition of being RESTful, then don't label it as such. This company, along with others (e.g.: Flickr and their infamous "REST" API), are responsible for turning "REST" into yet another buzzword.
eli 15y ago
In other words, something you might hack together if you never really gave any thought into what makes a good API.
andrewcooke 15y ago
This reminds me of Shu-Ha-Ri (Cockburn from way back - Agile as Coop): Shu - you don't know what you're doing (people here asking for help); Ha - you closely follow the rules (people here complaining); Ri - you understand the topic sufficiently to adapt and respond as necessary (people for whom this is really not a big deal). [Actually, now that I read the Wikipedia page for that, it's not quite right - apologies to any martial arts people out there http://en.wikipedia.org/wiki/Shuhari http://en.wikipedia.org/wiki/Shuhari]

Looks like an RPC-style API with multiple endpoints + custom authentication scheme.

vyrotek 15y ago

I was going to mention this. If this documentation completely removed the word 'REST' would we have cringed as bad?

Torn 15y ago
Probably not, but after seeing how nice REST API's can be with sensible url mappings, HATEOAS, HTTP methods as verbs, etc. it's almost insulting for sharefile to call it RESTful (presumably because it can return JSON?). Off the top of my head: - API method urls are all the same .aspx, regardless of method used - All calls are sent as GET (ignoring the whole point of HTTP methods in REST) - No HTTP method codes as responses for automated parsing - Custom authentication putting credentials in URL or in headers instead of relying on proven HTTP auth schemes we've been using for years (basic, form, etc) - Return format is done with get arguments instead of HTTP content negotiation in headers (not so bad) They've completely missed the boat here.
- euroclydon 15y ago
  The query string and headers ARE encrypted in https. And forms auth, that's just a post and a cookie. You can't require API clients to support cookies.
  - padobson 15y ago
    But, and excuse me if I'm wrong on this I'm looking for clarification, you should be forcing API clients to sign their requests with some sort of token - which might as well be a cookie. The difference being that a browser keeps track of the cookies for you, and any other client will have to keep track of any auth info itself (in a sqlite DB, xml file, held in memory, etc)
    - euroclydon 15y ago
      It's been a while since I've used AWS, but I consider their API to be the gold standard. IIRC, they have you concatenate a few fields plus a message length, and sign it with your secret key, and this signature is your authentication and anti-tamper mechanism.
    - csears 15y ago
      > sign their requests with some sort of token - which might as well be a cookie Using a token to sign requests is certainly a good idea, but you probably don't want to pass the token around using a cookie, even over HTTPS. Many browsers don't enforce good cookie security and will transmit cookies in the clear if an attacker can redirect the browser to a non-HTTPS URL on the same domain.
- panzerboy 15y ago
  Can you give an example of a nice REST API? I might have to create one soon and I need some inspiration. Thanks!
  - glassx 15y ago
    Maybe AtomPub? It respects HTTP methods, uses URIs to represent resources correctly, uses <links> to be discoverable (hypermedia), is self-descriptive, is stateful... It uses Atom/XML instead of JSON, but still... (but please correct me if it isn't a good example)
- arethuza 15y ago
  "API method urls are all the same .aspx, regardless of method used" Isn't it more the fact that they spend all of their efforts documenting the URI structure and very little on the media types used - which is very unRESTful.
- randomdata 15y ago
  I'm with you on just knowing we can do so much better. Some of the RESTful HATEOS based APIs coming out are simply beautiful. However, - API method urls are all the same .aspx, regardless of method used Extensions are meaningless. That is why we have Accept/Content-type headers. The HTTP spec even explicitly says to not use extensions to relay content information between client and server, from what I recall. - All calls are sent as GET (ignoring the whole point of HTTP methods in REST) I haven't read Fielding's dissertation in a while, but using the "Coles Notes" version from Wikipedia, I do not actually see using the verbs a requirement for REST. I do not recall REST even requiring HTTP. You can use any protocol you want, so long as it conforms to the principles. RESTful, on the other hand, does specify the use of HTTP verbs, but the site in question makes no mention of being RESTful. By not using the proper verbs, the site does appear to violate the caching rules of REST though, I'll give you that. - Custom authentication putting credentials in URL or in headers (neither of which are encrypted over https) The entire https payload is encrypted, headers and all. REST says nothing about how authentication should be implemented. - Return format is done with get arguments instead of HTTP content negotiation in headers (not so bad) This falls under the same as using extensions. Though I will agree with you that it is a reasonable compromise in some cases, such as using a browser where you can't reasonably set your own headers.
lvillani 15y ago
I believe it's important to keep things honest. If an API is nowhere near the definition of being RESTful, then don't label it as such. This company, along with others (e.g.: Flickr and their infamous "REST" API), are responsible for turning "REST" into yet another buzzword.

eli 15y ago

In other words, something you might hack together if you never really gave any thought into what makes a good API.

andrewcooke 15y ago

This reminds me of Shu-Ha-Ri (Cockburn from way back - Agile as Coop): Shu - you don't know what you're doing (people here asking for help); Ha - you closely follow the rules (people here complaining); Ri - you understand the topic sufficiently to adapt and respond as necessary (people for whom this is really not a big deal). [Actually, now that I read the Wikipedia page for that, it's not quite right - apologies to any martial arts people out there http://en.wikipedia.org/wiki/Shuhari http://en.wikipedia.org/wiki/Shuhari]