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

51–60 of 139 posts

Re: Designing a Pragmatic RESTful API

#51

Post by vyrotek »

icebraining wrote: post #48
vyrotek wrote: post #44

Earlier quoted context omitted.

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.

Sorry. I shouldn't have over simplified that point about it being just data. I meant to emphasize that you really want to just call an operation and "just do some work". The data being just function parameters with optional data returned.

I'm currently working on a few large B2B APIs and it's been difficult to implement REST. The value of these APIs come from the actual work performed and not just updating the state of a few rows in a DB. I have very "business logic" heavy endpoints which take many parameters and return very different payloads. As much as I hate it, sometimes business and practicality comes before purity. :)

I actually asked for some feedback in a comment below buried somewhere: https://news.ycombinator.com/item?id=5819821

Re: Designing a Pragmatic RESTful API

#52

Post by mtrimpe »

kailuowang wrote: post #49
mtrimpe wrote: post #47

Earlier quoted context omitted.

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)?

My first solution was assuming you could not revert. If you want to allow revert then the client would first call /posts/X/versions, get a list of all versions and then either do

    PATCH /posts/X
    { "version": "older-revision" }
or

    PATCH /posts/X/versions/older-revision
    { "active": true }
Access control is completely orthogonal to this; so for your sample case you would just return a 403 for any other calls (like e.g. POSTs to /posts/X/versions)

Re: Designing a Pragmatic RESTful API

#53

Post by protonfish »

kailuowang wrote: post #43
protonfish wrote: post #40

Earlier quoted context omitted.

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.

Irrespective of what is good or bad design, defining an action in the URL goes against the most critical REST principles. Design it whatever way you like, but if you do this, it is not RESTful and you should not refer to it as such.

Re: Designing a Pragmatic RESTful API

#54

Post by dragonwriter »

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?

> 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 extended relation names and/or hypertext-enabled mark-up for existing standard media types. Any effort spent describing what methods to use on what URIs of interest should be entirely defined within the scope of the processing rules for a media type (and, in most cases, already defined by existing media types). [Failure here implies that out-of-band information is driving interaction instead of hypertext.]

[1] http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...

Re: Designing a Pragmatic RESTful API

#55

Post by l1ghtm4n »

Excellent article. I've just written up REST API design patterns for our group here and it maps very closely to the guidelines you've outlined. Many other posts about REST design are lacking real world experience items like rate limiting.

Re: Designing a Pragmatic RESTful API

#56

Post by buro9 »

We've built a first version of an API that we have in testing at the moment, and it follows a lot of the things laid out in an ebook✝ and in the linked article.

The epiphany we had was that whilst machines do access the API, the developer is always the customer and user. Everything we do should help the developer, and if we have to break rules to help them... then largely we should.

I've built a couple of very pure REST APIs in the past, but had a lot of developers pushing back and demanding something simpler. To not use media types so precisely, to be more accepting of what data is sent, to provide meta-data along with the resource (most seem to prefer an envelope), to prefer composite resources over very decoupled interfaces, etc.

This time, I haven't even tried to build a pure REST API. This time I've just mixed together the bits that developers I've spoken to liked and prefer. Adjusting as I went depending on how it was received.

http://microcosm-cc.github.io/

That's the docs for it, and we get the arguments out the way right at the beginning. All we're trying to do is build an API that helps developers get their task done. We're not done, and I know it's not pure anything... but the feedback we're getting is far more positive than any pure REST API I've ever built.

✝ If you are willing to give out a fake email address then this free eBook is a great resource and has a lot of sane information presented clearly: http://pages.apigee.com/web-api-design-ebook.html

Re: Designing a Pragmatic RESTful API

#57

Post by icebraining »

vyrotek wrote: post #51
icebraining wrote: post #48

Earlier quoted context omitted.

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.

Sorry. I shouldn't have over simplified that point about it being just data. I meant to emphasize that you really want to just call an operation and "just do some work". The data being just function parameters with optional data returned. I'm currently working on a few large B2B APIs and it's been difficult to implement REST. The value of these APIs come from the actual work performed and not just updating the state…

Oh no, I certainly don't think there's anything wrong or impure about not implementing REST. REST is an architectural style that, by imposing some constraints, gives you certain benefits (Fielding's paper talks about this). It's not a panacea, and it's certainly not right for every case.

Just don't make an RPC API and call it RESTful ;)

Re: Designing a Pragmatic RESTful API

#58

Post by dragonwriter »

vyrotek wrote: post #23

Great article. I'm actually in the middle of building out a new API. I've built many RESTful APIs but I'm starting to rethink of a couple of things with this new one. Does anyone have any good resources on when it's NOT appropriate to use REST? Or is the assumption that it should generally work for anything if you model it right? I ask this because the API I'm building is for a B2B product and lot of the "actions" ar…

> Or is the assumption that it should generally work for anything if you model it right?

It should generally work for anything if you model it right.

> I ask this because the API I'm building is for a B2B product and lot of the "actions" are not state change requests.

How can anything both be an action and not be a state change request?

> In fact, they are a lot of verbs which fire off lots of business logic and don't really map well to a single entity.

A "verb that firest off lots of business logic" sounds like a RPC-style metaphor.

In a REST architecture -- and they don't necessarily map perfectly so with more description I might characterize this differently -- I'd characterize that as most likely a entity creation (HTTP POST) action (the entity being a particular invocation of the underlying logic, and containing all the necessary parameters.)

> Some endpoints also need to return very large and deeply filled entities in a single call.

How does this conflict with REST. REST has nothing against "large and deeply filled entities". (Remember that HTTP is itself a RESTful API, and obviously is designed for a use case where "large and deeply-filled entities" are frequently returned.)

You may want to define specific media types for each of these types of entities to do REST properly, but since in practice you are going to have to define the structure of the entity returned no matter what application architectural style you are using, this isn't really a substantial extra workload for REST.

Re: Designing a Pragmatic RESTful API

#59

Post by icebraining »

HNJohnC wrote: post #32

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.

Look, REST wasn't something invented in Fielding's study, it was a destillation of an architectural style that was extremely common: Websites. Many ( and at the time, most) are stateless, follow HATEOAS, using only a standardized set of methods, etc.

There's nothing difficult or impractical about REST, and the proof is that we use it every day.

Now, it's not aplicable to every case, of course. In those cases, just use something else, and don't call it REST.

Re: Designing a Pragmatic RESTful API

#60

Post by memset »

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 great) for implementing oauth authentication for my own API?

Post reply on HN