Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Designing a Pragmatic RESTful API

vinaysahni.com

Post reply on HN
Print view View original

31–40 of 139 posts

Re: Designing a Pragmatic RESTful API

#31

Post by icebraining »

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…

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

Re: Designing a Pragmatic RESTful API

#32

Post by HNJohnC »

I've been spending many weeks reading articles and books about building a RESTful api. There are a lot of 'ivory tower' guidance articles and books on REST that make little sense in the trenches.

That article sums up exactly my own distillation into practical terms of all that information out there. I wish I had read it first.

Re: Designing a Pragmatic RESTful API

#33

Post by progx »

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…

The problem with limit is the programming overhead in frontend and backend.

If you want a performance advantage you must parse the limit-params and select only the needed fields from db and send them to client. But this make the backend complicated.

If something is misspelled (frontend/backend) you need more time to find the error.

It is easier and cleaner provide some additional calls for specific data (like lastLogin).

If you use something like Backbone in frontend, you are happy to access all needed data so easy, why restrict them?

Ok if you have an heavy used performance critic application, you can start optimizing. But why, welcome to the cloud, add some processes ;-)

Re: Designing a Pragmatic RESTful API

#34

Post by protonfish »

icebraining wrote: post #31
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…

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

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.

Re: Designing a Pragmatic RESTful API

#35

Post by joeblau »

Great article. I wish you would have written this a year ago when I needed this info. I had to learn all of this stuff the hard way. I'm definitely going to use this as a first resource to give to people that I know who are building restful APIs.

I'm slightly a bigger proponent of HATEOAS, but if you don't need it yet, I think you can always add it in later. I've been the giver and receiver of bad things when it's not followed, but that is generally around massive projects.

Re: Designing a Pragmatic RESTful API

#36

Post by oxtopus »

Something to consider, the author advocates json responses across the board, which is pretty good advice, however, it's incompatible with `204 No Content` responses (also recommended). If you're building a client that connects to an API that could potentially return a `204 No Content` response, you can't assume that there will be json in the body and automatically parse the response.

Re: Designing a Pragmatic RESTful API

#37

Post by kailuowang »

RESTful design is still one of the tricky problems I meet on a daily basis. For example, I have blog application in which each blog entry can have multiple versions in its revision history. What should the restful api look like to provide the ability to revert to a certain version?

Re: Designing a Pragmatic RESTful API

#38

Post by beaumartinez »

kailuowang wrote: post #37

RESTful design is still one of the tricky problems I meet on a daily basis. For example, I have blog application in which each blog entry can have multiple versions in its revision history. What should the restful api look like to provide the ability to revert to a certain version?

Off the top of my head—have a BlogPost and a BlogPostVersion resource. BlogPostVersion has all the content, and BlogPost simply has a canonical URL and a link to a BlogPostVersion.

You could then PATCH the BlogPost with the link to whatever BlogPostVersion you want to update to.

Curious to see what others would recommend.

Re: Designing a Pragmatic RESTful API

#39

Post by arethuza »

icebraining wrote: post #29
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…

REST only looks complicated because you're seeing it with RPC goggles. In REST, you don't call functions, you just ask for documents and send documents to the server(s). There's nothing particularly complicated in it, it's just a different approach. That said, this article isn't particularly faithful to REST.

I guess the way I think of REST is that you make requests of different kinds to resources, some of the responses containing documents that contain references to other resources - and all you need to start is the "root" document for the service and an understanding of what the contents of each document mean.

Re: Designing a Pragmatic RESTful API

#40

Post by protonfish »

kailuowang wrote: post #37

RESTful design is still one of the tricky problems I meet on a daily basis. For example, I have blog application in which each blog entry can have multiple versions in its revision history. What should the restful api look like to provide the ability to revert to a certain version?

Um, how about POST /blog/id/ and in the request body revert=version#

Seriously REST isn't a mystery. I think the problem is few understand what it is. Here is my 30-second version:

1. Identification of resources and manipulation through representations. This means a network resource should have a URL that is the same no matter what you are doing to it - getting changing, removing, modifying or any custom manipulation. For the Web, use HTTP verbs and request body data to define the actions.

2. Self-descriptive error messages. Don't return 200 OK for everything. Use status codes and verbose response bodies to describe what happened.

3. Hypermedia as the engine of application state. Expose ALL functionality in HTML using hyperlinks and forms.

Post reply on HN