Fix issue-287 - document the X-Requested-By header, fix the documentation for the scale REST endpoint's request body.

Author: moreaut

site/rest.md

@@ -7,7 +7,16 @@ You can access most of the REST services using `GET`, for example:
 * To obtain a list of domains, send a `GET` request to the URL `/operator/latest/domains`.
 * To obtain a list of clusters in a domain, send a `GET` request to the URL `/operator/latest/domains/<domainUID>/clusters`.
 
-All of the REST services require authentication.  Callers must pass in a valid token header and a CA certificate file.  The `X-Requested-By` header is not required.  Callers should pass in the `Accept:/application/json` header.
+All of the REST services require authentication.  Callers must pass in a valid token header and a CA certificate file.  Callers should pass in the `Accept:/application/json` header.
+
+To protect against Cross Site Request Forgery (CSRF) attacks, the Operator REST api requires that you send in a `X-Requested-By` header when you invoke a REST endpoint that makes a change (for example when you POST to the `/scale` endpoint).  The value is an arbitrary name such as 'MyClient'. For example, when using curl:
+
+```
+curl ... -H X-RequestedBy:MyClient ... -X POST .../scaling
+```
+
+If you do not pass in the X-Requested-By header, then you'll get a 400 (bad request) response without any details explaining why the request is bad.
+The X-Requested-By header is not needed for requests that only read, for example when you GET any of the Operator's REST endpoints.
 
 If using `curl`, you can use the `-k` option to bypass the check to verify that the operator's certificate is trusted (instead of `curl --cacert`).
 

site/scaling.md

@@ -32,11 +32,20 @@ The `/scale` REST endpoint accepts an HTTP POST request and the request body sup
 
 ```
 {
-    "configuredManagedServerCount": 3
+    "managedServerCount": 3
 }
 ```
 
-The `configuredManagedServerCount` value designates the number of WebLogic Server instances to scale to.  Note that the scale resource is implemented using the JAX-RS framework, and so a successful scaling request will return an HTTP response code of `204 (“No Content”)` because the resource method’s return type is void and does not return a message body.
+The `managedServerCount` value designates the number of WebLogic Server instances to scale to.  Note that the scale resource is implemented using the JAX-RS framework, and so a successful scaling request will return an HTTP response code of `204 (“No Content”)` because the resource method’s return type is void and does not return a message body.
+
+When you POST to the `/scale` REST endpoint, you must send in a `X-Requested-By` request value.  The value is an arbitrary name such as 'MyClient'.  For example, when using curl:
+
+```
+curl -v -k -H X-Requested-By:MyClient -H Content-Type:application/json -H Accept:application/json -H "Authorization:Bearer ..." -d { "managedServerCount": 3 } https:/.../scaling
+```
+
+If you omit the header, you'll get a 400 (bad request) response without any details explaining why the request was bad.
+
 
 ## What does the operator do in response to a scaling request?