[deleted]
Obviously off-topic, but under what circumstances would you ever be returning a field containing a "password" (even a hashed one) over the network in the first place?
[deleted]
Designing a Pragmatic RESTful API
101–110 of 139 posts
Re: Designing a Pragmatic RESTful API
#102I 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!
That's great as long as you're using something with efficient random-access (SQL). If your datastore/back-end is btree-based, however (say, CouchDB for example, or Google search results) you're better off with 'next', 'prev', 'first', etc. pagination. Asking for the 50,000th record means skipping the first 49,999! So, you may be painting your back-end into a corner by counting on random-access being an efficient operation.
Re: Designing a Pragmatic RESTful API
#103REST isn't enough.
To do it right use the HATEOAS constraint. http://en.wikipedia.org/wiki/HATEOAS
And use application/hal+json http://stateless.co/hal_specification.html
The more we follow these simple constraints the more we can start to build tooling to consume any API without having to know much about it ahead of time.
That said, well written article.
Re: Designing a Pragmatic RESTful API
#104Earlier 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.
Maybe HTTP is simply missing the INVOKE verb for executable documents.
Sounds good to me :)
Re: Designing a Pragmatic RESTful API
#105I 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…
Does your JSON response at the root entry point to the API return something signifying what all possible operations are? Does the JSON representation of a Employee object returned URLs as a part of the body for the resource addresses for any "child" objects? I don't think it can be considered HATEOAS if the answer to either is no.
>Does your JSON response at the root entry point to the API return something signifying what all possible operations are?
Why, no, it doesn't, because it takes 3 parameters, each of which can take 10,000 possible values, and I don't want to transmit a trillion options every time someone pings the root.
I mean, I considered documenting how to pass the parameters on a client's first entry but the HATEOAS crowd told me I was just re-creating RPC, and I agreed. So no HATEOAS.
Re: Designing a Pragmatic RESTful API
#106Earlier quoted context omitted.
Does your JSON response at the root entry point to the API return something signifying what all possible operations are? Does the JSON representation of a Employee object returned URLs as a part of the body for the resource addresses for any "child" objects? I don't think it can be considered HATEOAS if the answer to either is no.
Of course not - it is called HYPERMEDIA as the engine of application state (not JSON.) That's why it's not called JATEOAS. The information you are asking for sounds more appropriate in an OPTIONS request.
> Of course not - it is called HYPERMEDIA as the engine of application state (not JSON.)
If the answer to those questions is no (whether the format of the response is JSON or anything else), then you aren't using hypermedia as the engine of application state.
Re: Designing a Pragmatic RESTful API
#107REST isn't enough. To do it right use the HATEOAS constraint. http://en.wikipedia.org/wiki/HATEOAS And use application/hal+json http://stateless.co/hal_specification.html The more we follow these simple constraints the more we can start to build tooling to consume any API without having to know much about it ahead of time. That said, well written article.
> REST isn't enough.
> To do it right use the HATEOAS constraint.
The HATEOAS constraint is part of REST; if you aren't using it, you aren't doing REST.
Re: Designing a Pragmatic RESTful API
#108I 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!
That's great as long as you're using something with efficient random-access (SQL). If your datastore/back-end is btree-based, however (say, CouchDB for example, or Google search results) you're better off with 'next', 'prev', 'first', etc. pagination. Asking for the 50,000th record means skipping the first 49,999! So, you may be painting your back-end into a corner by counting on random-access being an efficient oper…
The header's ranges-specifier doesn't specify a syntax, so you can use a docid-based pager just as easily.
Re: Designing a Pragmatic RESTful API
#109Earlier quoted context omitted.
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.
I think what you have said is correct of how, but not why.
However I think what this whole discussing is missing is the properties that you derive by adhering to a REST design.
I think there should be some tests of a design to see if you are actually getting the benefits of REST.
For example in a REST design you can re-arrange the internal URL's in a server and the site is still usable to clients because they are following links from the root.
Why do we want this ability to rearrange URLs?
Re: Designing a Pragmatic RESTful API
#110This 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.
It seems more complicated to me to define a document format that provides URLS, than to just tell people what the URLs are.
In my mind I think of some things e.g.: google search, as a function not a resource. Trying to think about what the resource might be seems tangential to what I am trying to do.