Document required indentation for policy creation

[bwaz]

Update documents to reflect required indentation with package definitions for the REST examples
http://www.openpolicyagent.org/documentation/references/rest/

working example:
package opa.examples
<white space>import request.example.a

failing example:
package opa.examples
import request.example.a
error output:
{ "Code": 400, "Message": "opaexample:1: expected rule (request.example.a must be declared inside a rule)" }

[tsandall]

Hi @bwaz, can you show (exactly) how you're calling the API?

If you're using cURL with the -d then the module may not be encoded as you expect. From the cURL man page:

              If you start the data with the letter @, the rest should be a file name to read the data from, or - if you  want
              curl  to read the data from stdin. Multiple files can also be specified. Posting data from a file named 'foobar'
              would thus be done with --data @foobar. When --data is told to read from a file like that, carriage returns  and
              newlines will be stripped out. If you don't want the @ character to have a special interpretation use --data-raw
              instead.

E.g., if you run curl -d @somefile.rego localhost:8181/v1/policies/opaexample -X PUT (where somefile.rego contains the failing example above) the request message body will be:

	0x0040:  4876 e85d 4876 e85d 5055 5420 2f76 312f  Hv.]Hv.]PUT./v1/
	0x0050:  706f 6c69 6369 6573 2f74 6573 7420 4854  policies/test.HT
	0x0060:  5450 2f31 2e31 0d0a 486f 7374 3a20 6c6f  TP/1.1..Host:.lo
	0x0070:  6361 6c68 6f73 743a 3831 3831 0d0a 5573  calhost:8181..Us
	0x0080:  6572 2d41 6765 6e74 3a20 6375 726c 2f37  er-Agent:.curl/7
	0x0090:  2e35 312e 300d 0a41 6363 6570 743a 202a  .51.0..Accept:.*
	0x00a0:  2f2a 0d0a 436f 6e74 656e 742d 4c65 6e67  /*..Content-Leng
	0x00b0:  7468 3a20 3434 0d0a 436f 6e74 656e 742d  th:.44..Content-
	0x00c0:  5479 7065 3a20 6170 706c 6963 6174 696f  Type:.applicatio
	0x00d0:  6e2f 782d 7777 772d 666f 726d 2d75 726c  n/x-www-form-url
	0x00e0:  656e 636f 6465 640d 0a0d 0a70 6163 6b61  encoded....packa
	0x00f0:  6765 206f 7061 2e65 7861 6d70 6c65 7369  ge.opa.examplesi
	0x0100:  6d70 6f72 7420 7265 7175 6573 742e 6578  mport.request.ex
	0x0110:  616d 706c 652e 61                        ample.a

Notice the whitespace between the package directive and import directive has been dropped.

If you are using cURL, I recommend the --data-binary instead of -d/--data. Perhaps the docs should be updated to include a note about this.

[bwaz]

I'm calling like this:
curl -X PUT -H 'Content-Type: text/plain' http://localhost:8181/v1/policies/opaexample -d@opaexample

[tsandall]

OK, I will update the docs to include a note about this. Thanks for filing the issue!