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 explicitly requested in the Accept header) is the HTML fragment data wrapped in document markup with any forms necessary to expose all functionality in the browser (without JavaScript, but just enough CSS to make it pleasant.) It takes more work, but it not only is the best documentation, you can point the href property of JavaScript click handled hyperlinks right to the REST URIs for proper fallback.
Designing a Pragmatic RESTful API
21–30 of 139 posts
Re: Designing a Pragmatic RESTful API
#22Earlier quoted context omitted.
Doesn't this open you up to replay attacks though? Since you can't store that a token was already used..
Sure you can. Just include a timestamp, and expire the token, at, say, time + 90 seconds, or whatever makes sense for the application.
I get that you can expire it, and that helps, but it's not the same as use-once. Of course, just using a timeout is probably fine in many cases, especially if it's used with SSL. But replay attacks are still possible since there's a windows where it can be re-used.
Re: Designing a Pragmatic RESTful API
#23Great 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" are not state change requests. 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. Some endpoints also need to return very large and deeply filled entities in a single call.
I've started to investigate JSON-RPC, is that a good option?
Re: Designing a Pragmatic RESTful API
#24Well just as long as you use the right paradime REST is not always the best model to use.
I built a tool to use a third partys restful api for a when they should have built it using message queuing as that suited the application.
Re: Designing a Pragmatic RESTful API
#25Earlier quoted context omitted.
I did think that the criticism of XML for being hard to parse was a bit odd. Although I generally prefer JSON for simpler stuff XML is pretty easy to parse and sift through with XPath.
It has to do with the awful XML generated by automatic tooling (SOAP by WCF and JEE). Hand-generated XML can be just as nice as using hand-generated JSON, and on the other hand automatic domain-model-to-JSON mapping can be as ugly as any XML monstrosity.
Most languages have the concept of arrays and hashes, which map unambiguously & idiomatically to JSON via generic serializers.
Creating idiomatic XML, on the other hand, is a little more tricky. Should something be a tag or an attribute? What should it be named?
Re: Designing a Pragmatic RESTful API
#26"A RESTful API should be stateless. This means that request authentication should not depend on cookies or sessions. Instead, each request should come with some sort authentication credentials." Doesn't that mean you need to do a database lookup to verify the user with every request? Seems like a lot of overhead just for the sake of avoiding sessions.
Use an expiring token like mechanism. The API user first gets a token using credentials. Future requests use the token for authentication. A new token will be required periodically.
What are the benefits of doing this instead of just requiring authentication with every request?
Is it because the authentication part is a lot of work for the server or client?
Is it for the negligible (in this context) security benefits of not using the same secret-key for all traffic?
Re: Designing a Pragmatic RESTful API
#27This 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…
I think you are confusing the qualities of a good public API and a good internal/private one (for application architecture purposes only.) For internal, I believe REST is the way to go, no contest. Externally is a different story. You would typically only expose a subset of functionality, use different authentication schemes and use a format that can be more easily accessed across domains like JSONP.
Re: Designing a Pragmatic RESTful API
#28Earlier quoted context omitted.
It has to do with the awful XML generated by automatic tooling (SOAP by WCF and JEE). Hand-generated XML can be just as nice as using hand-generated JSON, and on the other hand automatic domain-model-to-JSON mapping can be as ugly as any XML monstrosity.
Though for the same dataset, XML will be slower to parse. For performance's sake use JSON.
> Though for the same dataset, XML will be slower to parse. For performance's sake use JSON.
Loading a huge JSON file is almost certainly slower than using a SAX parser for a huge XML file. Maybe there are SAX like approaches for JSON, too.
Re: Designing a Pragmatic RESTful API
#29This 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.
Re: Designing a Pragmatic RESTful API
#30Earlier quoted context omitted.
Though for the same dataset, XML will be slower to parse. For performance's sake use JSON.
> Though for the same dataset, XML will be slower to parse. For performance's sake use JSON. Loading a huge JSON file is almost certainly slower than using a SAX parser for a huge XML file. Maybe there are SAX like approaches for JSON, too.
Yes, it's called "streaming". Like in XML, you can also used a mixed approach. See e.g. https://sites.google.com/site/gson/streaming