{"id":2473,"date":"2015-02-24T16:04:27","date_gmt":"2015-02-24T14:04:27","guid":{"rendered":"https:\/\/upcloud.com\/global\/us\/resources\/tutorials\/getting-started-upcloud-api\/"},"modified":"2015-02-24T16:04:27","modified_gmt":"2015-02-24T14:04:27","slug":"getting-started-upcloud-api","status":"publish","type":"tutorial","link":"https:\/\/upcloud.com\/global\/resources\/tutorials\/getting-started-upcloud-api\/","title":{"rendered":"Getting started using the UpCloud API"},"content":{"rendered":"\n<p class=\"wp-block-paragraph\">This is a quick introduction to the UpCloud API. It will help you through the first steps of connecting to the API and automating your cloud servers using your favourite programming language. The programmable API is available at https:\/\/api.upcloud.com, which encompasses all of the functionality of the UpCloud control panel and then some; if you want to get started on your own, head straight to the full <a href=\"https:\/\/developers.upcloud.com\/\" target=\"_blank\" rel=\"noopener\">API documentation<\/a>.<\/p>\n\n\n\n<div class=\"wp-block-buttons is-layout-flex wp-block-buttons-is-layout-flex\">\n<div class=\"wp-block-button\"><a class=\"wp-block-button__link wp-element-button\" href=\"https:\/\/signup.upcloud.com\/\">Test hosting on UpCloud!<\/a><\/div>\n<\/div>\n\n\n\n<h2 class=\"wp-block-heading\">Creating API credentials<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">The first step in getting started with our API is to create a separate API user. You can do this at the <a href=\"https:\/\/hub.upcloud.com\/people\" target=\"_blank\" rel=\"noopener\">UpCloud Control Panel<\/a>\u00a0using a subaccount. Your API account name and password are very similar to an API ID and key pair, with the added benefit of being able to set them yourself.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Create a new subaccount for the API access by clicking the <em>Create subaccount<\/em>\u00a0button.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large\"><img decoding=\"async\" src=\"https:\/\/upcloud.com\/media\/upcloud-control-panel-people-1024x525.png\" alt=\"-\" class=\"wp-image-43463\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">Then, fill in the necessary details:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Choose your API username<\/li>\n\n\n\n<li>Set the API password<\/li>\n\n\n\n<li>Enter the contact details for your API credentials<\/li>\n\n\n\n<li>When set, click the\u00a0<em>Create subaccount<\/em>\u00a0button to save<\/li>\n<\/ul>\n\n\n\n<figure class=\"wp-block-image size-large\"><img decoding=\"async\" src=\"https:\/\/upcloud.com\/media\/upcloud-control-panel-subaccount-864x1024.png\" alt=\"-\" class=\"wp-image-43464\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">Next, go to the Permissions tab and enable API access in the permissions<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Grant the permissions to the resources you want the API to have access to<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">By default, the API account will have full permissions to any resources it creates but no access to existing servers or storage. You can grant additional permissions using the server, storage, and tag access options.<\/p>\n\n\n\n<figure class=\"wp-block-image size-large\"><img decoding=\"async\" src=\"https:\/\/upcloud.com\/media\/upcloud-control-panel-permissions-837x1024.png\" alt=\"-\" class=\"wp-image-43465\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">You can create as many dedicated API accounts as you need. We recommend creating separate API credentials for each application and external service you use.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Note that you should restrict the API subaccount\u00a0from your other UpCloud services. If you are programming automation against the UpCloud API, take care handling the credentials.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Running basic API requests<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">Once you have created your API account, let\u2019s try your first request. To quickly test the API, use a tool such as <a href=\"http:\/\/www.getpostman.com\/\" target=\"_blank\" rel=\"noopener\">Postman<\/a>&nbsp;(or any other API toolkit of your choice) to get started. The goal is to have the following dialogue working.<\/p>\n\n\n\n<pre class=\"wp-block-preformatted\">GET \/1.3\/account<\/pre>\n\n\n\n<pre class=\"wp-block-preformatted\">HTTP\/1.0 200 OK\n{\n    \"account\" : {\n        \"credits\" : \"10000\",\n        \"username\" : \"username\"\n    }\n}<\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">Using a GET request, enter the API address\u00a0https:\/\/api.upcloud.com with the API version number and the desired command to the request URL line. Then, select the Basic Auth option and set your username and password. After filling in the request details, click the <em>Send<\/em> button to run the query.<\/p>\n\n\n\n<figure class=\"wp-block-image\"><a href=\"https:\/\/upcloud.com\/global\/community\/\n\/tutorials\/\nwp-content\/uploads\/2017\/02\/postman_account_get.png\" target=\"_blank\" rel=\"noopener\"><img decoding=\"async\" src=\"https:\/\/upcloud.com\/media\/postman_account_get-2.png\" alt=\"Postman GET Account\" class=\"wp-image-3222\" \/><\/a><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">The reply will be shown in the bottom half of the Postman window under the <em>Body<\/em> tab.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">The authentication method of our API is HTTP Basic authentication, where the Authorization header should contain your API username and Base64 encoded password. More precisely:<\/p>\n\n\n\n<pre class=\"wp-block-preformatted\"># Python3\nimport base64\nbase64.b64encode(\"username:password\".encode())<\/pre>\n\n\n\n<pre class=\"wp-block-preformatted\"># Node.js\nnew Buffer(\"username:password\").toString('base64');\n<\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">Postman&#8217;s authorization header line should look as shown below with your Base64 encoded credentials.<\/p>\n\n\n\n<figure class=\"wp-block-image\"><a href=\"https:\/\/upcloud.com\/global\/community\/\n\/tutorials\/\nwp-content\/uploads\/2017\/02\/postman_basic_auth_header.png\" target=\"_blank\" rel=\"noopener\"><img decoding=\"async\" src=\"https:\/\/upcloud.com\/media\/postman_basic_auth_header-2.png\" alt=\"Postman Basic Auth header\" class=\"wp-image-3226\" \/><\/a><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">Using a similar request by just replacing the query target from <tt>account<\/tt> to <tt>server<\/tt> you can get the full list of servers your API account is allowed to access.<\/p>\n\n\n\n<pre class=\"wp-block-preformatted\">GET \/1.3\/server<\/pre>\n\n\n\n<pre class=\"wp-block-preformatted\">HTTP\/1.0 200 OK\n{\n    \"servers\": {\n        \"server\": [\n            {\n                \"core_number\": \"1\",\n                \"hostname\": \"example.upcloud.com\",\n                \"license\": 0,\n                \"memory_amount\": \"1024\",\n                \"plan\": \"1xCPU-1GB\",\n                \"state\": \"started\",\n                \"tags\": {\n                    \"tag\": []\n                },\n                \"title\": \"Example UpCloud server\",\n                \"uuid\": \"00e8051f-86af-468b-b932-4fe4ac6c7f08\",\n                \"zone\": \"fi-hel1\"\n            }\n        ]\n    }\n}<\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">You should now be able to form similar requests to the ones above using the API. For example,&nbsp;<tt>GET \/1.3\/server\/00e8051f-86af-468b-b932-4fe4ac6c7f08<\/tt>, will reply with full details of that specific host when you include the UUID of one of your servers in a query.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Using the API programmatically<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">The API can be accessed using any language that has proper HTTP libraries. The following snippet shows how you could take advantage of the UpCloud API using Python3.<\/p>\n\n\n\n<pre class=\"wp-block-preformatted\">import http.client\nimport base64\n\nconn = http.client.HTTPSConnection(\"api.upcloud.com\")\nauth = base64.b64encode(\"username:password\".encode())\nheaders = {\"Authorization\": \"Basic \" + auth.decode()}\n\nconn.request(\"GET\", \"\/1.3\/account\", None, headers)\nres = conn.getresponse()\nprint( res.read().decode() )\n<\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">For a bit more sensible approach, the example below shows how you could structure the code for a better approach. The BaseAPI forms a generic API (GET) request extended by the Account class to form the same API request as above. Adding additional GET requests would now be much easier.<\/p>\n\n\n\n<pre class=\"wp-block-preformatted\">import http.client\nimport base64\n\nclass BaseAPI:\n    api = \"api.upcloud.com\"\n    api_v = \"1.3\"\n    token = base64.b64encode(\"username:password\".encode())\n\n    '''\n    Performs a GET request to a given endpoint in UpCloud's API.\n    '''\n    def get(self, endpoint):\n        conn = http.client.HTTPSConnection(self.api)\n        url = \"\/\" + self.api_v + endpoint\n        headers = {\n            \"Authorization\": \"Basic \" + self.token.decode(),\n            \"Content-Type\": \"application\/json\"\n        }\n        conn.request(\"GET\", url, None, headers)\n        res = conn.getresponse()\n        self.printresponse(res.read())\n\n    '''\n    Prints the response (bytes) as a string to the user\n    '''\n    def printresponse(self, res):\n        data = res.decode(encoding=\"UTF-8\")\n        print(data)\n\nclass Account(BaseAPI):\n    endpoint=\"\/account\"\n\n    def do(self):\n        self.get(self.endpoint)\n\nif __name__ == \"__main__\":\n    Account().do()\n<\/pre>\n\n\n\n<h2 class=\"wp-block-heading\">More about the UpCloud API<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">These are just some of the simplest examples of what the UpCloud API allows you to do. Now that you have mastered the API usage, proceed to\u00a0deploy a new server with the\u00a0<a href=\"https:\/\/upcloud.com\/global\/resources\/tutorials\/deploying-server-upcloud-api\">UpCloud API<\/a>.<\/p>\n","protected":false},"author":3,"featured_media":27273,"comment_status":"open","ping_status":"closed","template":"","community-category":[271,247],"class_list":["post-2473","tutorial","type-tutorial","status-publish","has-post-thumbnail","hentry"],"acf":[],"_links":{"self":[{"href":"https:\/\/upcloud.com\/global\/wp-json\/wp\/v2\/tutorial\/2473","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/upcloud.com\/global\/wp-json\/wp\/v2\/tutorial"}],"about":[{"href":"https:\/\/upcloud.com\/global\/wp-json\/wp\/v2\/types\/tutorial"}],"author":[{"embeddable":true,"href":"https:\/\/upcloud.com\/global\/wp-json\/wp\/v2\/users\/3"}],"replies":[{"embeddable":true,"href":"https:\/\/upcloud.com\/global\/wp-json\/wp\/v2\/comments?post=2473"}],"version-history":[{"count":0,"href":"https:\/\/upcloud.com\/global\/wp-json\/wp\/v2\/tutorial\/2473\/revisions"}],"wp:attachment":[{"href":"https:\/\/upcloud.com\/global\/wp-json\/wp\/v2\/media?parent=2473"}],"wp:term":[{"taxonomy":"community-category","embeddable":true,"href":"https:\/\/upcloud.com\/global\/wp-json\/wp\/v2\/community-category?post=2473"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}