- Guides
- An introduction to APIs
- Implementation
Chapter 8: Implementation
By Bryan Cooksey • Published April 22, 2014
We made it! We now know everything there is to know about APIs...at an introductory level at least. So, with all this acquired knowledge, how can we put it to good use? In this chapter, we explore how to turn knowledge into working software.
From plan to product
As we have seen throughout this course, an API interaction involves two sides. When we are talking at the code-level, though, what we are really saying is that we need two programs that implement the API. A program implements an API when it follows the API's rules. In our pizza parlor example, a client that can make requests to the /orders endpoint using the correct headers and data format would be a client that implements the pizza parlor's API.
The server program is the responsibility of the company publishing the API. Back in Chapter 6, we looked at the process behind designing the API. After planning, the next step is for the company to implement their side by writing software that follows the design. The last step is to put the resulting program on a server.
Along with the server software, the company publishes documentation for the API. The documentation is one or more documents—typically webpages or PDFs—that explain how to use the API. It includes information like what authentication scheme to use, what endpoints are available, and how the data is formatted. It may also include example responses, code snippets, and an interactive console to play with the available endpoints. Documentation is important because it acts as a guide for building clients. It's where someone interested in using the API goes to learn how the API works.
With documentation in hand, there are a number of ways you can begin to use an API as a client. Let's examine three of those now.
HTTP clients
An easy way to start using an API is with an HTTP Client, a generic program that lets you quickly build HTTP requests to test with. You specify the URL, headers, and body, and the program sends it to the server properly formatted. These types of programs come in all sorts of flavors, including web apps, desktop apps, web browser extensions, and more.
The nice thing about generic HTTP clients is that you do not have to know how to program to use one. With the skills you've attained through this course, you now have the ability to read a company's API documentation and figure out the request you need to make to get the data you want. This small learning curve makes generic clients great for exploration and quick one-off tasks.
There are a couple downsides to this approach, however. First, you usually can't save your work. After you close the program, the requests you made are forgotten and you have to rebuild them the next time you need them. Another disadvantage is that you typically can't do much with the data you get back, other than look at it. At best, you have the ability to save the data into a file, after which it's up to you to do something interesting with it.
Writing code
To really harness the power of an API, you will eventually need custom software. This is where programming comes in. Being a discipline unto itself, we won't attempt to cover everything about software development, but we can give you some guidance for what writing an API client involves.
The first requirement is to gain some familiarity with a programming language. There are a bunch out there, each with its strengths and weaknesses. For simplicity’s sake, it is probably better that you stick to an interpreted language (JavaScript, Python, PHP, Ruby, or similar) instead of a compiled language (C or C++).
If you aren't sure which language to choose, a great way to narrow down the selection can be to find an API you want to implement and see if the company provides a client library. A library is code that the API owner publishes that already implements the client side of their API. Sometimes the library will be individually available for download or it will be bundled in an SDK (Software Development Kit). Using a library saves you time because instead of reading the API documentation and forming raw HTTP requests, you can simply copy and paste a few lines of code and already have a working client.
After you settle on a language, you need to decide where the code will run. If you are automating your own tasks, running the software from your work computer might be acceptable. More frequently, you will want to run the code on a computer better suited for acting as a web server. There are quite a few solutions available, including running your code on shared hosting environments, cloud services (like Amazon Web Services), or even on your own physical servers at a data center.
A third important decision is to figure out what you will do with the data. Saving results into a file is easy enough, but if you want to store the data in a database or send it to another application, things become more complex. Pulling data out of a database to send to an API can also be challenging.
At this point we can pause and remind you to not be too intimidated by all this new information. You should not expect to know everything about implementing APIs on your first attempt. Take solace knowing that there are people who can help (open source communities, developers for-hire, and potential project collaborators) and lots of resources available online to facilitate learning.
Once you master the basics, there are plenty more topics to learn about in the rich realm of software development. For now, if you succeed at learning a programming language and getting a library up and running, you should celebrate. You will be well on your way to making the most of APIs!
Give Zapier a try
If coding is beyond your current skill set or time constraints, there is a nifty tool we know of that empowers you to easily interact with APIs. OK, you probably saw this coming: it's Zapier! Our Developer Platform offers a way for you to implement an API that you then interact with as an app on Zapier. Through button clicks and filing out forms, you can implement nearly any API you want.
What makes using the Developer Platform easy is that we have done a lot of the programming for you. Zapier has code in place to make requests, all you have to do is fill in the details. Think of using the platform a bit like using a generic HTTP Client; you tell us a bit about the endpoints and we'll do the rest. The additional benefit is that once you have Zapier talking with an API, you have lots of options for what to do with the data you get back. Also, if you get stuck, you are welcome to reach out to the friendly support team, where you have API experts ready to help you out.
Chapter 8 recap
In this chapter, we discussed how an API design becomes working software. We talked about ways that you can begin using APIs.
The key terms we learned were:
- Implement: Writing software that obeys the rules of an API
- Documentation: Webpages, PDF's, etc. that explain the rules of an API
- Library: Code released by an API publisher that implements the client portion of their API
Ideas for using APIs at work
Think about ways you might be able to use an API in your working life. To get the juices going, here are a few ideas:
- You need some quick stats from a SaaS (Software as a Service) application you use. Firing up an HTTP Client to make a few requests could be a fast way to get the information you need.
- You have a labor-intensive task that needs to get done and there isn't time to have a developer friend lend a hand. Grabbing a client library and creating a quick program could be a big timesaver.
- You really want to move data between two SaaS apps on a continual basis, but you don't have the resources to build a client for each app from scratch, nor a good place to run that code. Using the Zapier Developer Platform could be a low-cost way to get the applications connected.
Conclusion
We've come a long way in this course. We started with questions like "What is a client?" and end with ideas for how to build them. Even if you decide not to try your hand at implementing an API, we hope you feel comfortable when they come up in conversation. You now have a sense of what an API is, what it does, and how you can leverage one to benefit your business.
Maybe you run a company and see the value in providing an API to your customers. Or perhaps you regularly do pesky, time-consuming tasks that you are excited to have automated. Whatever the case may be, we hope you find the knowledge you've gained valuable. Please share this course with anyone you think could benefit from it and spread the word that APIs are awesome!
Previous chapter:
