Designing a Pragmatic RESTful API • Hacker News Board

Re: Designing a Pragmatic RESTful API

#61

Post by protonfish » Tue, Jun 04, 2013, 4:49 PM UTC

veesahni wrote: post #50

protonfish wrote: post #21

I am not sure I follow his point about why HATEOAS is not practical, but I know that I have been able to make it work in my own REST APIs using content types. I only return JSON if the Accept header specifies "application/json". (Which is probably what you should be doing anyhow.) I usually also allow an HTML fragment response for the "text/html-fragment" Accept type. The default response type (or if "text/html" is e…

HATEOAS is first and foremost about the API being self describing. Quoting from wikipedia: "A REST client enters a REST application through a simple fixed URL. All future actions the client may take are discovered within resource representations returned from the server."

I would disagree and say it is first and foremost about using hypermedia as the engine of application state.

Re: Designing a Pragmatic RESTful API

#62

Post by johns » Tue, Jun 04, 2013, 4:49 PM UTC

ExpiredLink wrote: post #45

_pmf_ wrote: post #2

RESTful: almost correct usage of HTTP verbs to implement something that has nothing to do with REST. But it sure sounds nice.

The obligatory "you're doing it wrong" comment following virtually all REST articles.

Once people stop calling it the wrong thing, the discussion can be about something else.

I also hate this nitpicking, but it's clearly not going away so you're better off not inviting it by using the term incorrectly.

Re: Designing a Pragmatic RESTful API

#63

Post by dragonwriter » Tue, Jun 04, 2013, 4:51 PM UTC

peterwwillis wrote: post #18

This is a well-written and informative article, kudos. That said, it reminds me how fucking overcomplicated REST HTTP API is for 99% of uses. As an API user, all I want is to call a function on a server, pass it some arguments and get a result. I want it to be dead simple, and REST is probably the opposite of that. Finally, it also occurs to me that most API calls may call one function which returns lots of data that…

> As an API user, all I want is to call a function on a server, pass it some arguments and get a result. I want it to be dead simple, and REST is probably the opposite of that.

How is this not dead simple in REST? Can you provide a specific example and how REST makes it complicated? Because I don't see it.

Re: Designing a Pragmatic RESTful API

#64

Post by buro9 » Tue, Jun 04, 2013, 4:52 PM UTC

memset wrote: post #60

Question: in all discussion about API design, the hairiest to me is always authentication. The article recommends SSL, but the internet says that "SSL is slow." Is there a guide to using SSL correctly, and techniques for making this more efficient? An SSL primer? It also recommends using oauth. There are hundreds of libraries for consuming oauth APIs. What exists (I'm a Python+Flask guy, but really any help would be…

SSL is not slow.

Grab the latest version of Nginx, turn on SPDY, enable SSL session cache.

You must always serve your API over SSL, as auth information is going to be in headers or the querystring and both would be readable by a MITM if you do not use SSL.

Nginx 1.4 statements to pay attention to (sample config):

    ssl                       on;
    ssl_certificate           /etc/ssl/domain.crt;
    ssl_certificate_key       /etc/ssl/domain.key;
    ssl_session_cache         shared:SSL:10m;
    ssl_session_timeout       10m;
    ssl_ciphers               RC4:HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;
    ssl_stapling              on;
    spdy_headers_comp         1;

If you're not using Nginx, why not? Just use it as a reverse proxy and drop it in front of whatever you are using.

Re: Designing a Pragmatic RESTful API

#65

Post by icebraining » Tue, Jun 04, 2013, 4:52 PM UTC

dragonwriter wrote: post #54

icebraining wrote: post #31

Earlier quoted context omitted.

Content types and HATEOAS are orthogonal properties, I'm not sure how you made the latter work using the former?

> Content types and HATEOAS are orthogonal properties, I'm not sure how you made the latter work using the former? They aren't orthogonal. Content-types are central to HATEOAS: From one of the key descriptions [1] of the HATEOAS constraint on REST: 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 ex…

That's media types. I was referring to the strings used in content-type, the HTTP header. You obviously need to support some media type, otherwise how would you represent a resource? But you don't need to support the Content-Type header to have HATEOAS.

Re: Designing a Pragmatic RESTful API

#66

Post by obelos » Tue, Jun 04, 2013, 4:55 PM UTC

I prefer providing a "Range" header for pagination. It's typically used for retrieving byte-range chunks of large objects, but it's also applicable to return a subset of a result set, like "Range: records=0-10". This has the drawback of not being easily applied from within a graphical browser, but I don't consider that a big priority for a REST API in the first place. Viva la curl!

Re: Designing a Pragmatic RESTful API

#67

Post by protonfish » Tue, Jun 04, 2013, 4:56 PM UTC

icebraining wrote: post #46

protonfish wrote: post #34

Earlier quoted context omitted.

Agreed, I am just trying to guess where the author is confused and reply in a useful manner. I am guessing that too many so-called "REST APIs" return JSON response bodies without explicitly requesting them in the Accept request header. By simply using the Accept header how it is meant to be used, you can return HATEOAS, JSON, XML or whatever format you want specifically designed for the target client.

What does it mean to "return HATEOAS"? HATEOAS is an architectural contrainst, not a format.

True. What I meant was a document that exposes all functionality of the network resource using hypermedia. I did not think that all responses had follow HATEOAS.) Some response should be OK returning partial data or limited functionality as long as something discoverable is explicit and comprehensive.

Re: Designing a Pragmatic RESTful API

#68

Post by T-hawk » Tue, Jun 04, 2013, 4:57 PM UTC

buro9 wrote: post #64

memset wrote: post #60

Question: in all discussion about API design, the hairiest to me is always authentication. The article recommends SSL, but the internet says that "SSL is slow." Is there a guide to using SSL correctly, and techniques for making this more efficient? An SSL primer? It also recommends using oauth. There are hundreds of libraries for consuming oauth APIs. What exists (I'm a Python+Flask guy, but really any help would be…

SSL is not slow. Grab the latest version of Nginx, turn on SPDY, enable SSL session cache. You must always serve your API over SSL, as auth information is going to be in headers or the querystring and both would be readable by a MITM if you do not use SSL. Nginx 1.4 statements to pay attention to (sample config): ssl on; ssl_certificate /etc/ssl/domain.crt; ssl_certificate_key /etc/ssl/domain.key; ssl_session_cache s…

While we're dispelling SSL myths, let me add the reminder that SSL does encrypt the URL and querystring and HTTP headers. It doesn't look like it in browsers because they still show the URL cleartext onscreen, but over the wire all of that is indeed inside the encryption envelope. Only the destination IP address isn't encrypted.

Re: Designing a Pragmatic RESTful API

#69

Post by dragonwriter » Tue, Jun 04, 2013, 4:59 PM UTC

icebraining wrote: post #65

dragonwriter wrote: post #54

Earlier quoted context omitted.

> Content types and HATEOAS are orthogonal properties, I'm not sure how you made the latter work using the former? They aren't orthogonal. Content-types are central to HATEOAS: From one of the key descriptions [1] of the HATEOAS constraint on REST: 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 ex…

That's media types. I was referring to the strings used in content-type, the HTTP header. You obviously need to support some media type, otherwise how would you represent a resource? But you don't need to support the Content-Type header to have HATEOAS.

> That's media types. I was referring to content-type, the HTTP header. You obviously need to support some media type, otherwise how would you represent a resource? But you don't need to support the Content-Type header to have HATEOAS.

If you are doing a REST architecture with a protocol other than HTTP, sure.

But since the Content-Type header is the mechanism by which HTTP communicates media types, and since in-band, rather than out-of-band, communication of resource locations and media types is essential to HATEOAS, the Content-Type header is a pretty important mechanism in HATEOAS when using HTTP.

Re: Designing a Pragmatic RESTful API

#70

Post by buro9 » Tue, Jun 04, 2013, 5:02 PM UTC

T-hawk wrote: post #68

buro9 wrote: post #64

Earlier quoted context omitted.

SSL is not slow. Grab the latest version of Nginx, turn on SPDY, enable SSL session cache. You must always serve your API over SSL, as auth information is going to be in headers or the querystring and both would be readable by a MITM if you do not use SSL. Nginx 1.4 statements to pay attention to (sample config): ssl on; ssl_certificate /etc/ssl/domain.crt; ssl_certificate_key /etc/ssl/domain.key; ssl_session_cache s…

While we're dispelling SSL myths, let me add the reminder that SSL does encrypt the URL and querystring and HTTP headers. It doesn't look like it in browsers because they still show the URL cleartext onscreen, but over the wire all of that is indeed inside the encryption envelope. Only the destination IP address isn't encrypted.

And whilst we're still here... SNI and SSL.

Thanks to Internet Explorer, and the early versions of the stock browser on Android, you will need a unique IPv4 address for your SSL endpoint.

You cannot safely serve multiple SSL sites on the same IP.✝

Basically: The hostname is also encrypted, so the SSL requests on some browsers require a unique IPv4 address. Your provider will give you one if you say the magic word "SSL" to them.

✝There are ways for most browsers, but not for IE and early Android browsers. Thankfully mobile device churn will cure us of the Android issue, but the affected IE versions will take longer to die.