AMBARI-8396 - Repository Version Management - Create documentation for API (Yurii Shylov via tbeerbower)

ambari-server/docs/api/v1/index.md

@@ -331,10 +331,25 @@ Task attempt resources are individual attempts at map or reduce tasks for a job.
 [Task Attempt Resources](taskattempt-resources.md)
 
 #### views
-Views offer a systematic way to plug-in UI capabilities to surface custom visualization, management and monitoring features in Ambari Web..
+Views offer a systematic way to plug-in UI capabilities to surface custom visualization, management and monitoring features in Ambari Web.
 
 [View Resources](view-resources.md)
 
+#### repository_versions
+Repository version resources contain information about available repositories with Hadoop stacks for cluster.
+
+[Repository Version Resources](repository-version-resources.md)
+
+#### stack_versions
+Stack version resources contain relationship between some resource and repository versions.
+
+[Stack Version Resources](stack-version-resources.md)
+
+#### rolling_upgrades_check
+Rolling upgrades check resources store information about successful/unsuccessful checks performed before rolling upgrade.
+
+[Rolling Upgrade Check Resources](rolling-upgrade-check-resources.md)
+
 Partial Response
 ----
 

ambari-server/docs/api/v1/repository-version-resources.md

@@ -0,0 +1,174 @@
+<!---
+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.
+-->
+
+# Repository Version Resources
+
+#####Create Instance
+New repository versions may be created through the API. At least one set of base repository URLs should be provided.
+
+    POST http://<server>:8080/api/v1/stacks/<stack_name>/versions/<stack_version>/repository_versions/
+    {
+      "RepositoryVersions": {
+        "repository_version": "2.2.1.1",
+        "display_name": "HDP-2.2.1.1"
+      },
+      "operating_systems": [
+        {
+          "OperatingSystems": {
+            "os_type": "redhat6"
+          },
+          "repositories": [
+            {
+              "Repositories": {
+                "repo_id": "HDP-2.2",
+                "repo_name": "HDP",
+                "base_url": "http://..."
+              }
+            },
+            {
+              "Repositories": {
+                "repo_id": "HDP-UTILS-1.1.0.20",
+                "repo_name": "HDP-UTILS",
+                "base_url": "http://..."
+              }
+            }
+          ]
+        }
+      ]
+    }
+
+#####Get Repository Versions
+The user may query for all repository versions of a particular stack.
+
+    GET http://<server>:8080/api/v1/stacks/<stack_name>/versions/<stack_version>/repository_versions/
+
+    {
+      href: "http://<server>:8080/api/v1/stacks/<stack_name>/versions/<stack_version>/repository_versions/",
+      items: [
+        {
+          href: "http://<server>:8080/api/v1/stacks/<stack_name>/versions/<stack_version>/repository_versions/1",
+          RepositoryVersions: {
+            id: 1,
+            stack_name: "HDP",
+            stack_version: "2.2"
+          }
+        },
+        {
+          href: "http://<server>:8080/api/v1/stacks/<stack_name>/versions/<stack_version>/repository_versions/2",
+          RepositoryVersions: {
+            id: 2,
+            stack_name: "HDP",
+            stack_version: "2.2"
+          }
+        }
+      ]
+    }
+
+#####Get Repository Version
+Returns single repository version.
+
+    GET http://<server>:8080/api/v1/stacks/<stack_name>/versions/<stack_version>/repository_versions/1
+
+    {
+      href: "http://<server>:8080/api/v1/stacks/<stack_name>/versions/<stack_version>/repository_versions/1",
+      RepositoryVersions: {
+        display_name: "HDP-2.2.0.0-2041",
+        id: 1,
+        repository_version: "2.2.0.0-2041",
+        stack_name: "HDP",
+        stack_version: "2.2",
+        upgrade_pack: "upgrade-2.2"
+      },
+      operating_systems: [
+        {
+          href: "http://<server>:8080/api/v1/stacks/<stack_name>/versions/<stack_version>/repository_versions/1/operating_systems/redhat5",
+          OperatingSystems: {
+            os_type: "redhat5",
+            repository_version_id: 1,
+            stack_name: "HDP",
+            stack_version: "2.2"
+          }
+        },
+        {
+          href: "http://<server>:8080/api/v1/stacks/<stack_name>/versions/<stack_version>/repository_versions/1/operating_systems/redhat6",
+          OperatingSystems: {
+            os_type: "redhat6",
+            repository_version_id: 1,
+            stack_name: "HDP",
+            stack_version: "2.2"
+          }
+        }
+      ]
+    }
+    
+#####Delete Repository Version
+Deregisters repository version. It won't be possible to remove repository version which is installed on any of the clusters.
+
+    DELETE http://<server>:8080/api/v1/stacks/<stack_name>/versions/<stack_version>/repository_versions/1
+
+#####Update Repository Version
+Updates repository version. It is possible to change display name and base URLs. 
+
+    PUT http://<server>:8080/api/v1/stacks/<stack_name>/versions/<stack_version>/repository_versions/1
+    
+    {
+      "RepositoryVersions": {
+        "display_name": "HDP-2.2.1.1",
+        "id": 1,
+        "repository_version": "2.2.1.1"
+      },
+      "operating_systems": [
+        {
+          "href": "http://<server>:8080/api/v1/stacks/<stack_name>/versions/<stack_version>/repository_versions/1/operating_systems/redhat5",
+          "OperatingSystems": {
+            "os_type": "redhat5"
+          },
+          "repositories": [
+            {
+              "href": "http://<server>:8080/api/v1/stacks/<stack_name>/versions/<stack_version>/repository_versions/1/operating_systems/redhat5/repositories/HDP-2.2",
+              "Repositories": {
+                "base_url": "http://...",
+                "os_type": "redhat5",
+                "repo_id": "HDP-2.2",
+                "repo_name": "HDP"
+              }
+            },
+            {
+              "href": "http://<server>:8080/api/v1/stacks/<stack_name>/versions/<stack_version>/repository_versions/1/operating_systems/redhat5/repositories/HDP-UTILS-1.1.0.20",
+              "Repositories": {
+                "base_url": "http://...",
+                "os_type": "redhat5",
+                "repo_id": "HDP-UTILS-1.1.0.20",
+                "repo_name": "HDP-UTILS"
+              }
+            }
+          ]
+        }
+      ]
+    }
+    
+#####Validate Base URL
+User may validate URLs of repositories before persisting.
+
+    POST http://<server>:8080/api/v1/stacks/<stack_name>/versions/<stack_version>/operating_systems/redhat5/repositories/HDP-UTILS-1.1.0.20?validate_only=true
+
+    {
+      "Repositories": {
+        "base_url": "http://..."
+      }
+    }
+    

ambari-server/docs/api/v1/rolling-upgrade-check-resources.md

@@ -0,0 +1,80 @@
+<!---
+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.
+-->
+
+# Rolling Upgrade Check Resources
+
+#####Get Check Results
+Retrieves results of rolling upgrade checks. All checks should have status PASS before running rolling upgrade.
+
+    GET http://<server>:8080/api/v1/clusters/<cluster_name>/rolling_upgrades_check/
+    
+    {
+      href: "http://<server>:8080/api/v1/clusters/<cluster_name>/rolling_upgrades_check/",
+      items: [
+        {
+          href: "http://<server>:8080/api/v1/clusters/<cluster_name>/rolling_upgrades_check/HOSTS_HEARTBEAT",
+          UpgradeChecks: {
+            cluster_name: "<cluster_name>",
+            id: "HOSTS_HEARTBEAT"
+          }
+        },
+        {
+          href: "http://<server>:8080/api/v1/clusters/<cluster_name>/rolling_upgrades_check/SECONDARY_NAMENODE_MUST_BE_DELETED",
+          UpgradeChecks: {
+            cluster_name: "<cluster_name>",
+            id: "SECONDARY_NAMENODE_MUST_BE_DELETED"
+          }
+        }
+      ]
+    }
+
+#####Example of checks execution
+Successful and unsuccessful check.
+
+    {
+      href: "http://<server>:8080/api/v1/clusters/<cluster_name>/rolling_upgrades_check/?fields=*",
+      items: [
+        {
+          href: "http://<server>:8080/api/v1/clusters/<cluster_name>/rolling_upgrades_check/HOSTS_HEARTBEAT",
+          UpgradeChecks: {
+            check: "All hosts must be heartbeating with the server unless they are in Maintenance Mode",
+            check_type: "HOST",
+            cluster_name: "1",
+            failed_on: [
+              
+            ],
+            id: "HOSTS_HEARTBEAT",
+            reason: "",
+            status: "PASS"
+          }
+        },
+        {
+          href: "http://<server>:8080/api/v1/clusters/<cluster_name>/rolling_upgrades_check/SECONDARY_NAMENODE_MUST_BE_DELETED",
+          UpgradeChecks: {
+            check: "The SECONDARY_NAMENODE component must be deleted from all hosts",
+            check_type: "SERVICE",
+            cluster_name: "<cluster_name>",
+            failed_on: [
+              "SECONDARY_NAMENODE"
+            ],
+            id: "SECONDARY_NAMENODE_MUST_BE_DELETED",
+            reason: "The SECONDARY_NAMENODE component must be deleted from host(s): c6401.ambari.apache.org. Please use the REST API to delete it.",
+            status: "FAIL"
+          }
+        }
+      ]
+    }

ambari-server/docs/api/v1/stack-version-resources.md

@@ -0,0 +1,168 @@
+<!---
+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.
+-->
+
+# Stack Version Resources
+
+#####Get Stack Versions
+Retrieves all stack versions.
+
+For cluster:
+
+    GET http://<server>:8080/api/v1/clusters/<cluster_name>/stack_versions/
+    
+    {
+      href: "http://<server>:8080/api/v1/clusters/<cluster_name>/stack_versions",
+      items: [
+        {
+          href: "http://<server>:8080/api/v1/clusters/<cluster_name>/stack_versions/1",
+          ClusterStackVersions: {
+            cluster_name: "<cluster_name>",
+            id: 1,
+            repository_version: 1,
+            stack: "HDP",
+            version: "2.2"
+          }
+        }
+      ]
+    }
+    
+
+For host:
+
+    GET http://<server>:8080/api/v1/hosts/<host_name>/stack_versions
+    {
+      href: "http://<server>:8080/api/v1/hosts/<host_name>/stack_versions",
+      items: [
+        {
+          href: "http://<server>:8080/api/v1/hosts/<host_name>/stack_versions/1",
+          HostStackVersions: {
+            host_name: "<host_name>",
+            id: 1,
+            repository_version: 1,
+            stack: "HDP",
+            version: "2.2"
+          }
+        }
+      ]
+    }
+    
+#####Get Stack Version
+Retrieves single stack version.
+
+For cluster:
+  
+      GET http://<server>:8080/api/v1/clusters/<cluster_name>/stack_versions/1
+      
+      {
+      href: "http://<server>:8080/api/v1/clusters/<cluster_name>/stack_versions/1",
+      ClusterStackVersions: {
+        cluster_name: "<cluster_name>",
+        id: 1,
+        repository_version: 1,
+        stack: "HDP",
+        state: "CURRENT",
+        version: "2.2",
+        host_states: {
+          CURRENT: [
+            "<host_name>"
+          ],
+          INSTALLED: [
+            
+          ],
+          INSTALLING: [
+            
+          ],
+          INSTALL_FAILED: [
+            
+          ],
+          OUT_OF_SYNC: [
+            
+          ],
+          UPGRADED: [
+            
+          ],
+          UPGRADE_FAILED: [
+            
+          ],
+          UPGRADING: [
+            
+          ]
+        }
+      },
+      repository_versions: [
+        {
+          href: "http://<server>:8080/api/v1/clusters/<cluster_name>/stack_versions/1/repository_versions/1",
+          RepositoryVersions: {
+            id: 1,
+            stack_name: "HDP",
+            stack_version: "2.2"
+          }
+        }
+      ]
+    }
+    
+For host:
+
+    GET http://<server>:8080/api/v1/hosts/<host_name>/stack_versions/1
+    
+    {
+      href: "http://<server>:8080/api/v1/hosts/<host_name>/stack_versions/1",
+      HostStackVersions: {
+        host_name: "<host_name>",
+        id: 1,
+        repository_version: 1,
+        stack: "HDP",
+        state: "CURRENT",
+        version: "2.2"
+      },
+      repository_versions: [
+        {
+          href: "http://<server>:8080/api/v1/hosts/<host_name>/stack_versions/1/repository_versions/1",
+          RepositoryVersions: {
+            id: 1,
+            stack_name: "HDP",
+            stack_version: "2.2"
+          }
+        }
+      ]
+    }
+    
+#####Install Repository Version
+Performs install of given repository version on the resource.
+
+For cluster:
+
+    POST http://<server>:8080/api/v1/clusters/<cluster_name>/stack_versions/
+    {
+      "ClusterStackVersions": {
+        "stack": "HDP",
+        "version": "2.2",
+        "repository_version": "2.2.0.1-885"
+      }
+    }
+
+For host:
+
+    POST http://<server>:8080/api/v1/hosts/<host_name>/stack_versions/
+    
+    {
+      "HostStackVersions": {
+        "stack": "HDP",
+        "version": "2.2",
+        "repository_version": "2.2.0.1-885"
+      }
+    }