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

41–50 of 139 posts

Re: Designing a Pragmatic RESTful API

#41

Post by apidoc »

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?

All blogs and howtos only describe the change of API Access with new versions, but not how to handle different backend data versions.

One way is to use the newest version in Client and the Server has to convert old Data to new Data, then deliver to Client. But sometimes it not so easy, depend on complexity of your data.

Other way: convert all Data to new Version and change Data-Access in the old Api Version (but here is the Problem with: never change a running system, things that work before could go wrong). And if you have a huge site with many users, it is not possibly to interrupt the service.

To maintain many versions is for a short period ok, but for longer usage not practicable.

Did somebody have experience with that ?

Re: Designing a Pragmatic RESTful API

#42

Post by kailuowang »

beaumartinez wrote: post #38
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.

Thanks for the reply but maybe I didn't make our requirements clear. The history should be kept intact after the revert - a new version should be created that duplicates the reverted version and become the current version. Thoughts?

Re: Designing a Pragmatic RESTful API

#43

Post by kailuowang »

protonfish wrote: post #40
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…

I am not sure how RESTful that looks to me. I would like to route to the action from the url rather than having to read what's in the body. In your solution, I would need that body parser to differentiate this revert action from an update action.

Re: Designing a Pragmatic RESTful API

#44

Post by vyrotek »

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.

Sure, but peterwwillis was likely making the point that REST sometimes just gets in the way. REST itself is not complicated, but trying to make it work where it shouldn't can complicate what you're trying to do. Not all APIs can be modeled well with the "resource" or "document" concept. A lot of times all you really want is to ping an endpoint and get/post some data.

Re: Designing a Pragmatic RESTful API

#46

Post by icebraining »

protonfish wrote: post #34
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?

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.

Re: Designing a Pragmatic RESTful API

#47

Post by mtrimpe »

beaumartinez wrote: post #38
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.

Indeed. Creating a new version of your post should be a POST to /posts/X/versions. This would create something like /posts/X/versions/U-U-I-D.

Since REST is all about mapping to the underlying semantics of HTTP you'd then want to make /posts/X redirect to /posts/X/versions/U-U-I-D

Since there's nothing wrong with updating your resource under the hood (think of e.g. http://www.weather.com/weather/right-now/) posts/X would simply always redirect to the latest version.

If you don't always use the latest version by definition, then you'd probably do a PATCH with the new version id to /posts/X, or a PATCH with 'active: true' to /posts/X/version/O-L-D.

Re: Designing a Pragmatic RESTful API

#48

Post by icebraining »

vyrotek wrote: post #44
icebraining wrote: post #29

Earlier quoted context omitted.

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.

Sure, but peterwwillis was likely making the point that REST sometimes just gets in the way. REST itself is not complicated, but trying to make it work where it shouldn't can complicate what you're trying to do. Not all APIs can be modeled well with the "resource" or "document" concept. A lot of times all you really want is to ping an endpoint and get/post some data.

If you just want to get/post some data, why are you modeling the system using functions (computations)? If anything, a document oriented approach is much more suited for that use case.

Re: Designing a Pragmatic RESTful API

#49

Post by kailuowang »

mtrimpe wrote: post #47
beaumartinez wrote: post #38

Earlier quoted context omitted.

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.

Indeed. Creating a new version of your post should be a POST to /posts/X/versions. This would create something like /posts/X/versions/U-U-I-D. Since REST is all about mapping to the underlying semantics of HTTP you'd then want to make /posts/X redirect to /posts/X/versions/U-U-I-D Since there's nothing wrong with updating your resource under the hood (think of e.g. http://www.weather.com/weather/right-now/ ) posts/X…

If I understand your solution correctly, does it mean that it's now the client's obligation to get the content from the revert-to version and create a new version and POST it to /posts/X/versions? That should work, but what if I don't wanna give the client the ability to create version arbitrarily (only allowed to revert to a pre-existing version)?

Re: Designing a Pragmatic RESTful API

#50

Post by veesahni »

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."

Post reply on HN