docs, working updates to rest connection and using rest connection in…

… the rest client transform. apache#4369

docs/hop-user-manual/modules/ROOT/pages/metadata-types/rest-connection.adoc

@@ -0,0 +1,49 @@
+////
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+  http://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+////
+:page-pagination:
+:description:
+
+= REST connection
+
+image:icons/rest.svg[]
+
+A REST connection is a connection to a REST api that can be reused from transforms like the xref:pipeline/transforms/rest.adoc[REST client].
+
+The REST connection is a generic purpose metadata item. A transform or action that uses a REST connection can override its properties when required.
+
+== Related Plugins
+
+xref:pipeline/transforms/rest.adoc[REST client]
+
+== Options
+
+[options="header"]
+|===
+|Option |Description
+|Name|The name to be used for this REST connection
+|Base URL|The URL to use as the base URL for any API calls. The base URL will need to be appended from client transforms or actions that use it to make detailed API calls.
+|Test URL|A full URL that can be used to test this REST connection. If no test URL is specified, the base URL will be used to perform connection tests.
+|Authorization header name|The Authentication/Authorization header name to use for the connection.
+|Authorization prefix|An (optional) prefix to use for the authentication/authorization header value (e.g. `Bearer`)
+|Authorization value|The Authentication/Authorization header value to use for the connection. This could be a token, an API key etc.
+|===
+
+Use the `Test` button to authenticate against the test or base URL, using the authentication/authorization header name, and (prefix + ) value.
+
+== Samples
+
+None

docs/hop-user-manual/modules/ROOT/pages/pipeline/transforms/rest.adoc

@@ -27,6 +27,11 @@ under the License.
 
 The REST Client transform enables you to consume RESTfull services. Representational State Transfer (REST) is a key design idiom that embraces a stateless client-server architecture in which the web services are viewed as resources and can be identified by their URLs.
 
+The REST client transform can use a pre-defined xref:metadata-types/rest-connection.adoc[REST connection] or use full URLs directly. +
+When using a REST connection, the URL (hard-coded or accepted from a field) will be considered a path relative to the base URL defined in the REST connection. Header values that are specified in the `Headers` tab of the transform will overwrite any headers with the same name that were defined in the REST connection.
+
+When used without a REST connection, the full URL needs to be specified.
+
 == Example
 The REST client Transform returns a "result" field (can change the name), and the field is often used in the next transform. For example, it can be read in by a JSON input transform that extracts the fields specified on the Fields tab.
 
@@ -52,6 +57,7 @@ The General tab is where you enter basic connection information for accessing a
 |===
 |Option|Description
 |Transform name|Name of this transform as it appears in the pipeline workspace
+|REST Connection|The (optional) xref:metadata-types/rest-connection.adoc[REST connection] to use for the base URL and authentication/authorization header name and value.
 |URL|Indicates the path to a resource
 |Accept URL from field|Designates the path to a resource is defined from a field
 |URL field name|Indicates the field from which the path to a resource is defined

plugins/misc/rest/src/main/java/org/apache/hop/metadata/rest/RestConnection.java

@@ -33,8 +33,8 @@
     key = "restconnection",
     name = "i18n::RestConnection.name",
     description = "i18n::RestConnection.description",
-    image = "",
-    documentationUrl = "")
+    image = "rest.svg",
+    documentationUrl = "/metadata-types/rest-connection.html")
 public class RestConnection extends HopMetadataBase implements IHopMetadata {
 
   private ClientBuilder builder;