[jira] [Commented] (SOLR-7405) Update ref guide curl examples to eliminate Content-Type

["Hoss Man (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/SOLR-7405?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=14497069#comment-14497069 ] 

Hoss Man commented on SOLR-7405:
--------------------------------


Here is a concrete example of the type of scenerio i'm confident we'll see if we update the ref guide to include a lot of example "curl" calls that do *not* explicitly set the Content-Type header...

----

Let's suppose we have the following example in our ref guide (it's a real example from this existing page, but with the Content-Type removed per what yonik's suggestion) ...

https://cwiki.apache.org/confluence/display/solr/Uploading+Data+with+Index+Handlers

{noformat}
curl -X POST 'http://localhost:8983/solr/my_collection/update?json.command=false' --data-binary '
{
  "id": "1",
  "title": "Doc 1"
}'
{noformat}

A novice developer, who knows nothing about Solr, or curl, tweaks the URL in this example to match their Solr server & collection, sees that it works, and fairly easily intuits that {{-X POST}} means it's a POST request, and that {{-data-binary}} is the POST body.

This developer then goes off and uses the basic HTTP library of the langauge they are using for their application to try and send the same command to solr -- for the sake of argument, let's assume they are using python.  They write the following code...

{code}
from httplib2 import Http
from pprint import pprint
h = Http()
data = ""
resp, content = h.request("http://localhost:8983/solr/gettingstarted/update?json.command=false", 
                          "POST", 
                          body="{ \"id\": \"1\", \"title\": \"Doc 1\"}")
pprint(resp)
pprint(content)
{code}

...and it doesn't work.  instead of getting a happy status code they get an HTTP 415 error and a message about "Missing ContentType"

So our developer is already confused.  Maybe they give up.  Maybe they are intuitive enough to realize based on the error message that they need to add this line to their {{h.request()}} method call...
{noformat}
headers = {'Content-type': 'application/json'},
{noformat}
...at which point their code will start to work, but it stil confuses the hell out of them and gives them a bad taste in their mouth (why did Solr work with the curl w/o a content-type, but not with their code? what other seemingly straight forward things will break in weird ways like this?)

Even worse: let's assume that instead of immediately guessing that they needed to add a "Content-Type" header to their request, they try to be smart and use a proxy or a wiresniffer to try and compare the request coming from curl vs the request coming from their application -- or they searh the curl docs to figure out what default Content-Type it's sending -- to see what the differences are between the example request that works, and their request that doesn't.

What they are going to find is that curl is sending a default of "Content-Type: application/x-www-form-urlencoded" -- suggesting that Solr _expects_ "application/x-www-form-urlencoded" to be specified even when the data is JSON ... which should rightly scare the shit out of any developer considering using a system: "WHy does solr _expect_ an obviously broken Content-Type and give an error if it's not specified???"

If they actually _try_ to add this bogus "application/x-www-form-urlencoded" to their python code, it still won't work -- now they are going to get a really perplexing 400 error response with the message "missing content stream"

At this point, i know i would sure as shit give up.





> Update ref guide curl examples to eliminate Content-Type
> --------------------------------------------------------
>
>                 Key: SOLR-7405
>                 URL: https://issues.apache.org/jira/browse/SOLR-7405
>             Project: Solr
>          Issue Type: Improvement
>          Components: documentation
>            Reporter: Hoss Man
>            Priority: Minor
>
> SOLR-7217 added a special work arround to solr to autodetect the correct content-type if the user-agent indicates curl is in use and the content-type specified is the curl default ("application/x-www-form-urlencoded")
> while this is certianly a nice to have convenience for people who forget to specify a Content-Type when using curl, there was quite a bit of back and forth on the ref guide TODO page about wether all example curl calls in the ref guide should explicitly take advantage of this for brevity.
> I'm opening this issue in the interest of having a more structured place for this discussion.



--
This message was sent by Atlassian JIRA
(v6.3.4#6332)

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: dev-help@lucene.apache.org