How Not to write a "REST" API • Hacker News Board

Re: How Not to write a "REST" API

#31

Post by breaker05 » Wed, Feb 01, 2012, 4:21 PM UTC

Eduard wrote: post #12

What else is flawed with this API? I'd be nice to have a "Dos and Don'ts in REST API design", with the Don'ts exemplified with Sharefile's API.

I'd like to know the same thing. Aside from everyone complaining that they used the term RESTful wrong, is there anything really wrong? It authenticates securely over HTTPS so I am confused what is wrong. Saying it's not complaint I don't really follow either. Thanks for any help.

Re: How Not to write a "REST" API

#32

Post by SomeOtherGuy2 » Wed, Feb 01, 2012, 4:22 PM UTC

alexchamberlain wrote: post #21

SomeOtherGuy2 wrote: post #17

Earlier quoted context omitted.

In what way is it not compliant?

Custom headers should be prepended with "X-". Also, the top line should read POST rest/getAuthID.aspx HTTP/1.1 Correction : Use of "X-" has been depreciated in a draft resolution. Edit : As mentioned below, it isn't compliant in its use of the verbs (GET/POST etc).

Custom headers do not REQUIRE a prefix. So the lack of prefix does not make it non-compliant. In fact, the HTTP RFC doesn't even say they SHOULD have a prefix. And RFC822 which defines headers only says that protocol mandated headers MUST NOT be prefixed with "X-". Also, there's a draft proposal to deprecate the "X-" header prefix as it does more harm than good: http://tools.ietf.org/html/draft-ietf-appsawg-xdash-02

Second, absolute URIs are perfectly valid, all HTTP/1.1 servers MUST accept them: http://www.w3.org/Protocols/rfc2616/rfc2616-sec5.html#sec5.1

Re: How Not to write a "REST" API

#33

Post by carbocation » Wed, Feb 01, 2012, 4:23 PM UTC

SomeOtherGuy2 wrote: post #20

carbocation wrote: post #18

Earlier quoted context omitted.

POSTed values won't show up in typical server logs, whereas with GET their plaintext password would normally be logged on every request. And POST over HTTPS keeps the POSTed values hidden from those who might listen, whereas with GET over HTTP it would just be out there in the URL.

You have no way of knowing what they log and don't log. If their server logs are compromised, you should be assuming their username/password database was as well. And HTTPS requests are encrypted. The whole request, including the "GET /someurl&password=s33krit HTTP/1.1" part. As I said, using POST doesn't add any additional security to this.

I agree with your concerns. But my comment was talking about "typical server logs" and HTTPS-POST vs HTTP-GET, while yours is addressing different issues.

Re: How Not to write a "REST" API

#34

Post by glassx » Wed, Feb 01, 2012, 4:24 PM UTC

panzerboy wrote: post #28

Torn wrote: post #11

Earlier quoted context omitted.

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 res…

Can you give an example of a nice REST API? I might have to create one soon and I need some inspiration. Thanks!

Maybe AtomPub? It respects HTTP methods, uses URIs to represent resources correctly, uses 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)

Re: How Not to write a "REST" API

#35

Post by bsenftner » Wed, Feb 01, 2012, 4:26 PM UTC

I don't hear people mention Drupal much here at HN. I assumed it was the learning curve; but anyway.. I point your interest over at https://drupal.org/node/783460 where the Services 3.0 module's REST API development framework is demonstrated with an example of creating a simple RESTful CRUD service. For ambitious WebApps & WebAPIs, Drupal provides great scaffolding for development. And it looks like the Drupal8 branch, a few years away, is 'headless' as in being configurable to only be an API endpoint with no "web site" necessary.

Re: How Not to write a "REST" API

#36

Post by Ethervoid » Wed, Feb 01, 2012, 4:26 PM UTC

Torn wrote: post #23

SomeOtherGuy2 wrote: post #16

Earlier quoted context omitted.

No they aren't sent plain-text: > https://subdomain.sharefile.com/rest/getAuthID.aspx Notice the https. The facepalm is just that there's no additional security in using POST vs GET.

Does HTTPs encrypt headers or just the body? Are both things they're offering secure?

"Everything in the HTTPS message is encrypted, including the headers, and the request/response load. With the exception of the possible CCA cryptographic attack described in limitations section below, the attacker can only know the fact that a connection is taking place between the two parties, already known to him, the domain name and IP addresses."

Re: How Not to write a "REST" API

#37

Post by SomeOtherGuy2 » Wed, Feb 01, 2012, 4:28 PM UTC

tmcneal wrote: post #22

SomeOtherGuy2 wrote: post #16

Earlier quoted context omitted.

No they aren't sent plain-text: > https://subdomain.sharefile.com/rest/getAuthID.aspx Notice the https. The facepalm is just that there's no additional security in using POST vs GET.

If you're using SSL then form data in a POST request will be encrypted. HTTP headers are always encrypted using SSL. What wasn't clear to me from the documentation is whether the 'username' and 'password' are form data, or are actually custom HTTP headers. The latter choice would certainly be a facepalm.

>If you're using SSL then form data in a POST request will be encrypted

So will everything else, including the URI being requested, and thus the query string in it. Which is why it makes no difference using GET or POST.

Re: How Not to write a "REST" API

#38

Post by padobson » Wed, Feb 01, 2012, 4:28 PM UTC

euroclydon wrote: post #19

Torn wrote: post #11

Earlier quoted context omitted.

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 res…

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.

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)

Re: How Not to write a "REST" API

#39

Post by Scybert » Wed, Feb 01, 2012, 4:33 PM UTC

Why do nerds constantly need to point to other people's failure to feel good?

Re: How Not to write a "REST" API

#40

Post by bryanh » Wed, Feb 01, 2012, 4:35 PM UTC

eli wrote: post #4

Most of the proprietary APIs I've had to work with were just as bad. Sometimes I wonder if the NDA they make you sign before seeing the API documentation is so that you won't be able to show anyone else how bad it is.

Poignant observation.

I'm currently working with an unnamed credit API and all calls, regardless of status, return 200. Options can be strung together in single GET parameter. All calls resolve to a single URL and the method is chosen get a GET param (which variant of that method is yet another param). And a person's information can be passed in via any slew GET params, or as POST'd XML.

Its a mess... anyone up for a Stripe of the credit/authentication world?