Tutorial Questions

[Adrian Mowat]

Hi 

Great job on this library!  It's really great to have this degree of control over a resource and it's making me think much deeper about REST than I have been previously and that is definitely a good thing.

Having worked through the tutorial on the Liberator homepage and I found a couple of areas where I couldn't get the code to work and a few areas were a bit more information would be helpful to newbies.  If we can figure these out between us, I would be very happy to help update the tutorial if someone can tell me how.

* On the getting started page, the recommended version of liberator is [liberator "0.9.0"] but the latest is 0.10.0.  I'm guessing it's just an oversight but is this there an incompatibility between the 2 versions I need to know about?

* I understand the principle of the examples on the decision graph page but I can't figure out how to get data into (-> ctx :request :params).  It's probably just me being a noob but the closest I can get is as follows (note that I have modified the example to pprint the request)...

$ curl -v -H "Accept: text/html" -d 'word=tiger' -X GET http://localhost:3000/secret

* About to connect() to localhost port 3000 (#0)

*   Trying ::1... connected

* Connected to localhost (::1) port 3000 (#0)

> GET /secret HTTP/1.1

> User-Agent: curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8y zlib/1.2.5

> Host: localhost:3000

> Accept: text/html

> Content-Length: 10

> Content-Type: application/x-www-form-urlencoded

> 

< HTTP/1.1 404 Not Found

< Date: Sun, 17 Nov 2013 10:43:32 GMT

< Vary: Accept

< Content-Type: text/html;charset=UTF-8

< Content-Length: 680

< Server: Jetty(7.6.1.v20120215)

< 

Sorry, try again.

<pre>{:request

 {:ssl-client-cert nil,

  :remote-addr "0:0:0:0:0:0:0:1",

  :scheme :http,

  :request-method :get,

  :query-string nil,

  :route-params {},

  :content-type "application/x-www-form-urlencoded",

  :uri "/secret",

  :server-name "localhost",

  :params {},

  :headers

  {"user-agent"

   "curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8y zlib/1.2.5",

   "content-type" "application/x-www-form-urlencoded",

   "content-length" "10",

   "accept" "text/html",

   "host" "localhost:3000"},

  :content-length 10,

  :server-port 3000,

  :character-encoding nil,

  :body #<HttpInput org.eclipse.jetty.server.HttpInput@20edcce1>}}

</pre>

* Connection #0 to host localhost left intact

* Closing connection #0

* Separately, when I try to PUT to /secret I get a 405 error - which is correct but I found a little confusing given that the example at the end of the previous page was using curl to do a put.  

* I can't get debug info in the browser at  http://localhost:3000/x-liberator/requests.  Here's my code

(def handler 

  (-> app 

      (wrap-trace :header :ui)))

(defonce server (run-jetty #'handler {:port 3000 :join? false}))

(defn start [] (.start server))

(defn stop [] (.stop server))

(defn restart [] 

  (stop)

  (start))

(restart)

* The POST example does not include the definition of the 'posts' ref so I had to figure out it was a vector

* There are a few inconsistencies in the navigation

  - The page after Decision Graph should be Debugging if it is to match the order in the side bar - although it mentions ETags which have not been introduced at that stage so maybe it should come later

  - Some of the pages don't have a "next page" link at the end 

Many Thanks

Adrian

[David Park]

​Hey, Adrian. I also have found Philipp's Liberator project has given me a much deeper understanding of the HTTP spec and REST practices. I am not really sure how user contribution is handled for github pages, so I'll let someone answer your questions about contributing to tidying up the tutorial.

I'll help you with what I can, but you will want to add a middleware to your request handler. The defacto way most clojure web applications are dealing with HTTP at the most basic level is using the excellent Ring library. Check out https://github.com/ring-clojure/ring for dependencies you need to add to your project.

Since you are sending content type text/html, you will want the wrap-params middleware, as documented at https://github.com/ring-clojure/ring/wiki/Concepts

(See also http://clojuredocs.org/ring/ring.middleware.params/wrap-params and http://mmcgrana.github.io/ring/ring.middleware.params.html)

If you start playing with application/json as a content type your application may accept, you will want to check out https://github.com/ring-clojure/ring-json, then, if you add wrap-json-params to your handler, then a request containing a ContentType of application/json will be put into the params attribute of the incoming request.

​To get the debugging info, add a trailing slash to http://localhost:3000/x-liberator/requests to be http://localhost:3000/x-liberator/requests/

Alternatively, if you are using a debugging console in your browser, then you can examine the request responses, and you can see a Link response header that brings you directly to the trace. Also, since you have specified the :header option as well as the :ui option, there will be a series of X-Liberator-Trace headers in the response as well.

Good luck!

--
You received this message because you are subscribed to the Google Groups "Liberator" group.
To unsubscribe from this group and stop receiving emails from it, send an email to clojure-libera...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

--
David Park
(m) +1.317.270.4287
daviddpark at gmail dot com

[Sean Johnson]

GitHub makes contributing to the docs, like the tutorial, super easy. It's all in your web browser, and you don't even need to fork the repo.

I updated the Liberator gh-pages branch README to provide step-by-step instructions .

My update won't be visible until the PR goes through, in the meantime you can read it here so you know how to fix the tutorial: 

https://github.com/belucid/liberator/blob/8648c4dfc9d14f276bf06decab7b56af8eef831c/README.md

Cheers,

Sean

[Adrian Mowat]

Hi David,

Thanks very much for your help.  Both of your suggestions worked.

The tutorial doesn't make it clear you need middleware for the example to work so although I have worked with Ring in the past but I didn't make the connection.  I'll see if I can update it.  The JSON middleware is excellent.  Thanks for the tip

Do you know if there is a reason the requests UI needs a trailing slash?  You've got me wondering if it's another part of the REST standard I didn't know existed but maybe I'm over thinking it

Many Thanks

Adrian

[Adrian Mowat]

Hi Sean,

That's ideal.  Thanks!

I'll make my updates and send in a pull request

Cheers

Adrian

[David Park]

I'm glad my response made sense! Regarding your question about the trailing slash, check out the file src/liberator/dev.clj which adds the trace routes to the handler.

You will see (def mount-url "/x-liberator/requests/") at the top of the file, and then the implementation of wrap-trace-uri further down in the file. Philipp reuses the mount-url for each of the following routes:

1) (GET (str base-url "trace.svg") [] (ƒ [_]  trace-svg))  ;the generated SVG

2) (ANY (str base-url "styles.css") [] styles) ;the relevant CSS file

3) (ANY [(str base-url ":id") :id #".+"] [id] #((log-handler id) %)) ;the prefix for a specific trace request

4) (ANY [(str base-url ":id")  :id #""] [id] list-handler) ;and the following 

    (ANY base-url [] list-handler) ;as a catch all for the top level "show me all recent requests"

It would be totally awesome if you could add the trailing slash to your pull request updating the documentation for http://clojure-liberator.github.io/liberator/tutorial/debugging.html

Cheers!

[Adrian Mowat]

All sorted.  Pull request submitted

https://github.com/clojure-liberator/liberator/pull/90/files

Thanks again for your help

Adrian