Here we'll use basic knowledge of Python to teach you how to leverage the extraordinary power of Web Application Interfaces (APIs) to extend the power of your programs. Most web hosting services, along with most web applications offer an API enabling you to include the ability of these third-party applications into your programs. You'll learn how to do this with a web hosting API, but once you work with one API, it's easier to learn to work with any Web API. You should come away from this article with the ability to learn and use the API for any service you can imagine.
You can use an API to automate tedious tasks you used to do manually, or you can use API's to achieve your objectives and to not only imagine but also create the applications you imagine. If you ever say, "I wish there were an app that did x, y, and z" there's a fair chance that learning how to use API's will take you a step closer to creating that app rather than wishing it existed.
Install Python and set up a virtual environment
If you've not done this yet, see this article on installing and setting up Python. Setting a virtual environment to separate each project from affecting other projects and the rest of your operating system's a good idea. You may be making changes in your virtual environment that could have unintended consequences.
Learn the basics of Python
This article doesn't require you to be an experienced developer, but it does assume some basic knowledge of Python. This <"introduction to Python"> should be enough to get you started, but you may want to seek other tutorials and opportunities to practice creating simple scripts.
Web Application Programming Interface (API)
An API is essentially a set of building blocks other services and programs provide for you to use to extend the reach of your programs. Webopedia goes into more detail with this definition:
An application program interface (API) is a set of routines, protocols, and tools for building software applications. An API specifies how software components should interact. Additionally, APIs are used when programming graphical user interface (GUI) components. A good API makes it easier to develop a program by providing all the building blocks. A programmer then puts the blocks together.
Section 1 - Using a web hosting API
Many web hosting services provide a web API to help you to programmatically interact with your account, create and delete virtual servers, and just about anything else you can imagine wanting to automate programmatically.
For this article, we'll use Digital Ocean's API as an illustrative example to introduce API's and some of what you can achieve using them.
Basic API Methods
As complex as API's seem to be at first glance, you're mostly sending HTTP requests to the server.
- GET - Asks the server for something
- POST - Asks the server to create something
- PUT - Asks the server to add something
- DELETE - Asks the server to delete something
The components of an API request
Whether you submit requests to a server directly using a web browser or programmatically, an API request must include these components:
- The URL
- The Headers - The headers contain the meta data the server needs to process your request (e.g., is the request from a mobile device?)
- The Body of the request contains the actual data (e.g., the details of the virtual server you want to spin up)
Call and response
You submit requests and initiate actions via commands submitted via http, meaning you can submit commands via URLs using a web browser or using some other application (e.g., curl) that can submit http requests. The API then processes your request or performs the action, and returns a response.
When you send a request to the server, it will send back responses, from confirming that it received the request, confirming that it's performing the task you requested, to returning the information you requested or completing the task you asked the server to perform. If something goes wrong, the server will inform you so you can take corrective action.
Most people recognize status codes because they're the same sort of codes returned when a website you're trying to reach doesn't work. For example, you've probably seen codes like "404 - page not found" and "500 - internal server error."d, which means success, because when everything's working there's no need for an error message when you're surfing the web without problems. Your web browser abstracts the 200 code away from you because it's not particularly useful to you.
When you're talking to servers programmatically, you'll want your program to know that it's request to the server succeeded or failed (and why it failed indicated by a status code).
There's a lot more to understanding the interaction with services using an API, but understanding the basic call and response pattern is enough to get you started using API's, building your knowledge and skill as you go.
Using an API to create a virtual server
To get you started using API's, we'll use Digital Ocean's API and Python to spin up a virtual server (DO calls them "Droplets) to our specifications. What you learn here will make it much easier to learn to use other web hosting providers API's as well as the API's of all sorts of services. Once you start using an API at one place, you immediately start looking around for how you can automate tasks involving all sorts of services and website that you use. It can end up both helping you up your technical game but also solve you a lot of time you used to spend doing everything manually.
Generating a unique API token.
When you want to use an API, you typically need to generate a unique, private API token, that you can use to access the API's services. In practice, you can think of your API token as a sort of password. You can generate multiple tokens as it's a good idea to use a different token for different applications.
Digital Ocean's process (very similar to others)
- Log into your Digital Ocean account, then go to your Control Panel.
- In the top navigation menu, click on API
Then click Generate New Token
Install a Python wrapper for Digital Ocean's API
Frequently, people develop "wrappers" for various programming languages to abstract away some of the detail to make writing scripts easier. For this example, we'll use a Python wrapper called python-digital ocean that has good reviews and starts on GitHub and Digital Ocean links to it, which adds more to the credibility of the wrapper.
The following assumes you've gone through the steps in the Python installation guide, which included instructions for installing the pip package manager, and that you've started a virtual environment, which is a best practice for each project (see installation article for details).
Here's the Github project maintained by the developer who was kind enough to create python-digitalocean to make it a bit easier to talk to the API using Python code.
Install the wrapper.
$ pip install -U python-digitalocean
Create a program called created.py with the following:
#!/usr/bin/env python3 import digitalocean import time droplet ='Your_Secret_API_Token', # replace with your API token name='Example1', # give your virtual server (droplet) a name region='sfo2', # choose region (find in "Droplets" in nav bar in Digital Ocean) image='ubuntu-14-04-x64', # Ubuntu 14.04 x64 # Choose your OS details size_slug='1GB', # Choose size backups=True) # The backup attribute's an example. There are many more things you can do. droplet.create() # Now the script runs the droplet create function! created = False # Initialize "created" to false # Run the following while and for loop until the server returns "completed," while not created: # while loop print('Creating Droplet') time.sleep(10) # This prints to your console every 10 seconds until droplet's completed
actions = droplet.get_actions() for action in actions: # A for loop embedded in the while loop action.load() if action.status == 'completed': # When the droplet's ready, completed is true created = True # Completed is true, and loop ends. # Once loop ends the program moves on to whatever's after the loop print("Droplet Completed!")
Let's run our program.
$ python created.py
Creating Droplet Creating Droplet Completed
The program iterated a few times (we've inserted a 10 second delay between) waiting for the status of "completed" to come back from the server, then it returns "Droplet completed" to you.
This script kept it simple, but you could add more to it to automate more of the process, including things like setting up the firewall, configuring ssh, etc. If you needed to create several virtual servers at once, you could modify the script to automate that process.
So you can see how learning a little Python and a bit about how API's work can save you a lot of manualwork, automating tedious tasks, making you more efficient at managing your web hosting. At the same time learning Python and how an API works, greatly increase your knowledge of how the web works, which will help you level up your technical skill and knowledge.
You've taken the first steps toward using programming to solve problems and work more efficiently. Keep going by seeking books, tutorials, and opportunities to create more useful scripts. You'll be amazed at how quickly you'll go from doing learning exercises to creating beneficial scripts.