Creating API credentials<\/h2>\n\n\n\n
The first step in getting started with our API is to create a separate API user. You can do this at the UpCloud Control Panel<\/a> using the workspace member accounts. Your API account name and password are very much comparable to an API ID and key pair with the added benefit of being able to set them yourself.<\/p>\n\n\n\n Create a new workspace member for the API access by clicking the Add member<\/em> button.<\/p>\n\n\n\n Enter the contact details for your API credentials, set the API password, and enable API access in the permissions.<\/p>\n\n\n\n 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 as needed using the server, storage, and tag access options.<\/p>\n\n\n\n Once done, click the Create subaccount<\/em> button at the bottom.<\/p>\n\n\n\n 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 Note that you should restrict the API subaccount from your other UpCloud services. Take care handling the credentials if you are programming automation against the UpCloud API.<\/p>\n\n\n\n Once you have created your API account, let\u2019s try your first request. To quickly test the API, use a tool such as Postman<\/a> (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 Using a GET request, enter the API address https:\/\/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. When you have filled in the request details, click the Send<\/em> button to run the query.<\/p>\n\n\n\n The reply will be shown in the bottom half of the Postman window under the Body<\/em> tab.<\/p>\n\n\n\n The authentication method of our API is the HTTP Basic authentication where the Authorization header should contain your API username and password Base64 encoded. More precisely:<\/p>\n\n\n\n In Postman the authorization header line should look as shown below with your Base64 encoded credentials.<\/p>\n\n\n\n Using a similar request by just replacing the query target from account<\/tt> to server<\/tt> you can get the full list of servers your API account is allowed to access.<\/p>\n\n\n\n You should now be able to form similar requests to the ones above using the API. For example, 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 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 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 that is 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 These are just a couple of the simplest examples of what the UpCloud API allows you to do. Now that you have got the hang of the API usage, continue on to deploying a new server with UpCloud API<\/a>.<\/p>\n","protected":false},"featured_media":27273,"comment_status":"open","ping_status":"closed","template":"","community-category":[109,122],"class_list":["post-24425","tutorial","type-tutorial","status-publish","has-post-thumbnail","hentry","community-category-upcloud-services","community-category-api"],"acf":[],"_links":{"self":[{"href":"https:\/\/studiogo.tech\/upcloudold\/wp-json\/wp\/v2\/tutorial\/24425","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/studiogo.tech\/upcloudold\/wp-json\/wp\/v2\/tutorial"}],"about":[{"href":"https:\/\/studiogo.tech\/upcloudold\/wp-json\/wp\/v2\/types\/tutorial"}],"replies":[{"embeddable":true,"href":"https:\/\/studiogo.tech\/upcloudold\/wp-json\/wp\/v2\/comments?post=24425"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/studiogo.tech\/upcloudold\/wp-json\/wp\/v2\/media\/27273"}],"wp:attachment":[{"href":"https:\/\/studiogo.tech\/upcloudold\/wp-json\/wp\/v2\/media?parent=24425"}],"wp:term":[{"taxonomy":"community-category","embeddable":true,"href":"https:\/\/studiogo.tech\/upcloudold\/wp-json\/wp\/v2\/community-category?post=24425"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}![\"Workspace](\"https:\/\/upcloud.com\/media\/workspace-members.png\")
<\/figure>\n\n\n\n![\"Create](\"https:\/\/upcloud.com\/media\/create-api-account.png\")
<\/figure>\n\n\n\nRunning basic API requests<\/h2>\n\n\n\n
GET \/1.3\/account<\/pre>\n\n\n\n
HTTP\/1.0 200 OK\n{\n \"account\" : {\n \"credits\" : \"10000\",\n \"username\" : \"username\"\n }\n}<\/pre>\n\n\n\n![\"Postman](\"https:\/\/upcloud.com\/media\/postman_account_get-2.png\")
<\/a><\/figure>\n\n\n\n# Python3\nimport base64\nbase64.b64encode(\"username:password\".encode())<\/pre>\n\n\n\n
# Node.js\nnew Buffer(\"username:password\").toString('base64');\n<\/pre>\n\n\n\n![\"Postman](\"https:\/\/upcloud.com\/media\/postman_basic_auth_header-2.png\")
<\/a><\/figure>\n\n\n\nGET \/1.3\/server<\/pre>\n\n\n\n
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\nUsing the API programmatically<\/h2>\n\n\n\n
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\nimport 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\nMore about the UpCloud API<\/h2>\n\n\n\n