December 19, 2016

How to Use an API: Just the Basics

Written by

8 min read

I used to work in customer support at a technology company where API connections that pulled user data from other programs were integral to the product. When I would explain to customers why we couldn’t access a particular piece of data, developers would often recommend the answer, “It’s not available over the API.”

At the time, I figured an API was like a USB port, and by connecting to that port, we would have access to everything in another program. Turns out, I was wrong.

ALSO READ: Zapier vs. IFTTT: The Best Tool for Task Automation

APIs are less like USB ports or fire hoses than they are like a person at a help desk in a foreign country. An API will not give you all of a program’s information or code (like a fire hose), because what would stop you from replicating the entire code base? Instead, an API provides you with data its programmers have made available to outside users. Even so, you have to know the language and ask the right questions in order to do anything with this data.

Top API management tools

If you already know how to use an API and just need the best way to manage them, check out this list of the top API management tools.

1 Mulesoft

Visit website

Use Mulesoft's Anypoint Platform to quickly design, test, and publish API products. Manage APIs, monitor and analyze usage, control access, and protect sensitive data with security policies. With Anypoint API Community Manager, transform portals into digital experiences that turn developers into evangelists by providing self-service API documentation, forums, support, and the personalized resources developers need to be successful.

Learn more about Mulesoft

2 Apigee

Visit website

Package your digital assets as APIs and monetize to unlock new revenue streams for your business with Apigee. Apigee supports the creation and configuration of a broad range of API packages, revenue models, reports, payment gateways, and developer portal integrations. These capabilities help API providers launch fast and gain value from their APIs sooner. Apply AI to your historical API metadata to predict the behavior of your APIs and automatically detect anomalies in real time.

Learn more about Apigee

3 Software AG

Visit website

Software AG's webMethods API Management allows you to reap the benefits of the API economy by managing the entire process of planning, designing, developing and securely exposing your APIs to external developers, partner and consumers. This Software AG solution provides an end-to-end tool chain, enabling you to leverage your current SOA investments for new API initiatives to get more value from your current assets while saving time and reducing the costs of development and training.

Learn more about Software AG

4 IBM API Connect

Visit website

Expertly secure and manage your entire API ecosystem across multiple clouds — including boosting socialization and monetization efforts — with industry-leading IBM API Connect. IBM API Connect® is a complete, intuitive and scalable API platform that lets you create, expose, manage and monetize APIs across clouds. This means you and your customers can power digital applications and spur innovation. Accelerate API developer productivity with simplified methods and a built-in toolkit.

Learn more about IBM API Connect

5 Kong

Visit website

Kong provides comprehensive visibility and empowers application teams to provide consistent security and governance across APIs and services. Empower your development teams to add fine-grained security and traffic policies that provide consistency across services and APIs. Use artificial intelligence to autonomously monitor traffic for anomalies to proactively identify performance and security incidents.

Learn more about Kong

6 Axway

Visit website

API Gateway provides a comprehensive platform for managing, delivering, and securing APIs. It provides integration, acceleration, governance, and security for Web API and SOA-based systems. Axway offers the full lifecycle API management for the next generation, as well as automating the discovery, reuse, and governance of all your APIs across multiple gateways, environments, and vendor solutions.

Learn more about Axway

7 Postman

Visit website

Postman is a collaboration platform for API development. Postman's features simplify each step of building an API and streamline collaboration so you can create better APIs. Quickly and easily send REST, SOAP, and GraphQL requests directly within Postman. Automate manual tests and integrate them into your CI/CD pipeline to ensure that any code changes won't break the API in production. Stay up-to-date on the health of your API by checking performance and response times at scheduled intervals.

Learn more about Postman

8 Cloud Elements

Visit website

Cloud Elements is the first API Integration Platform to virtualize APIs into unified data models that eliminate brittle, point-to-point connections. With your data at the center of a customized Application Ecosystem, you get a cost, scale and performance advantage so you can seize new opportunities, create new experiences and discover what’s next.

Learn more about Cloud Elements

9 SAP Integration Suite

Visit website

Publish, promote, and oversee APIs in a secure and scalable environment with the SAP API Management capability. Empower developer communities to monetize data and digital assets in new channels, devices, and UIs. Encourage more productive collaboration through the entire business ecosystem. Managing and monitoring APIs across various data platforms with real-time analytics, the API Management capability promotes co-innovation among employees, partners, and the developer community.

Learn more about SAP Integration Suite

10 Workato

Visit website

Workato is a single platform used to integrate apps and automate workflows without compromising security and governance. Rapidly accelerate growth by being automation-first across your organization. It enables companies to drive real time outcomes from business events. There is no coding required, and the platform utilizes Machine Learning and patented technology to make the creation and implementation of automations 10X faster than traditional platforms.

Learn more about Workato

What is an  API?

API stands for application programming interface. The most important part of this name is “interface,” because an API essentially talks to a program for you. You still need to know the language to communicate with the program, but without an API, you won’t get far.

When programmers decide to make some of their data available to the public, they “expose endpoints,” meaning they publish a portion of the language they’ve used to build their program. Other programmers can then pull data from the application by building URLs or using HTTP clients (special programs that build the URLs for you) to request data from those endpoints.

Endpoints return text that’s meant for computers to read, so it won’t make complete sense if you don’t understand the computer code used to write it.

TL;DR: An API allows one program to request data from another.

Why You Should Use an API

Computers make a lot of things easier, especially tasks that involve collecting and sorting through tons of data. Let’s say you wanted to know how many times a particular business partner submitted invoices to your company. You could feasibly go into your company’s invoice records, scan the “from” data input, and print each invoice individually for your audit.

On the other hand, if all invoices were uploaded to a central database, you could write a simple program that accesses that database and finds all the instances of the partner’s name. This would take much less time and be much more accurate.

Architecture of an API

APIs consist of three parts:

  • User: the person who makes a request
  • Client: the computer that sends the request to the server
  • Server: the computer that responds to the request

Someone will build the server first, since it acquires and holds data. Once that server is running, programmers publish documentation, including the endpoints where specific data can be found. This documentation tells outside programmers the structure of the data on the server. An outside user can then query (or search) the data on the server, or build a program that runs searches on the database and transforms that information into a different, usable format.

That’s super confusing, so let’s use a real example: an address book.

Back in the analog days, you’d receive a copy of the White Pages phone book, which listed every person in your town by name and address, in alphabetical order. If you needed a friend’s address, you could look them up by last name, find the address, then look up their street on the maps included in the back. This was a limited amount of information, and it took a long time to access. Now, through the magic of technology, all of that information can be found in a database.

Let’s build a database containing the White Pages for a fictional town called Happyville. The folks at Happyville_WP decided that when they built their database, they would create a few categories of information with nested data underneath. These are our endpoints, and they’ll include all the information the API will release to an outside program.

Here are the endpoints listed in the documentation for Happyville_WP:

  • /names
    • /first_name, /last_name
  • /addresses
    • /street_address, /email_address/
  • /phones
    • /home_phone, /mobile_phone

Obviously, this isn’t all the information that could be collected about a person. Even if Happyville_WP collected more private information about the Happyville residents (like birthdates and social security numbers), this data wouldn’t be available to outside programmers without knowing the language of those endpoints.

These endpoints tell you the language you must use to request information from the database. Should you want a list of all of the folks in Happyville with the last name Smith, you could do one of two things:

  1. Make a URL request in a browser for that information. This uses your internet browser as the client, and you will get back a text document in coding language to sort through. That URL might look something like this: http://api.happyville_wp.com/names?last_name=smith 
  2. Use a program that requests the information and translates it into usable form. You can code your own program or use a ready-made HTTP client.

The first option is great for making simple requests with only a few responses (all of the folks in a Happyville with the last name Xarlax, for example — I’m pretty sure there are only six households with this name in Happyville). The second option requires more coding fluency, but is great for programmers who want to use the database of another program to enhance their own apps.

Many companies use the open APIs from larger companies like Google and Facebook to access data that might not otherwise be available. APIs, in this case, significantly lower the barriers to entry for smaller companies that would otherwise have to compile their own data.

Actions You Can Take Through an API

Wow. Okay, so an API is how two computers talk to each other. The server has the data and sets the language, while the client uses that language to ask for information from the server (FYI, servers do not send data without a client requesting data, but developers have found some ways around this with webhooks). APIs can do anything!

Well, not so fast. The language and syntax of APIs severely limits their abilities. There are four types of actions an API can take:

  • GET: requests data from a server — can be status or specifics (like last_name)
  • POST: sends changes from the client to the server; think of this as adding information to the server, like making a new entry
  • PUT: revises or adds to existing information
  • DELETE: deletes existing information

When you combine the endpoints with these actions, you can search or update any available information over an API. You’ll need to check the API documentation to find out how to code these actions, as they’re all different.

While we’re talking about language and syntax, let’s cover the ways you can make a request on a server:

HTTP: hypertext transfer protocol. This is how you got to our site in the first place — by typing a URL in the search bar in your browser. This is a really easy way to access data, but it won’t come back to you in a pretty format if you request a lot of information. We’ll go into this further in just a second.

Text formats: XML, JSON. These are the main languages for accessing data over an API. When you receive your data, you will need to wade through the XML or JSON code to understand what the server gave you.

Start Using an API

Many of the API uses you’ll see in your daily business lives move information from one program to similar form fields in another program. This is especially useful when you’re trying to share information that you would otherwise have to enter repeatedly — e.g. sharing leads between your marketing automation platform and your CRM.

The uses and examples we’ll list here are much more basic and pull much less data than what your standard API is good for. But they’ll give you a good idea of the steps in the API process.

  1. Most APIs require an API key. Once you find an API you want to play with, look in the documentation for access requirements. Most APIs will ask you to complete an identity verification, like signing in with your Google account. You’ll get a unique string of letters and numbers to use when accessing the API, instead of just adding your email and password every time (which isn’t very secure — for more information on authorizations and verifications, read this).
  2. The easiest way to start using an API is by finding an HTTP client online, like REST-Client, Postman, or Paw. These ready-made (and often free) tools help you structure your requests to access existing APIs with the API key you received. You’ll still need to know some of the syntax from the documentation, but there is very little coding knowledge required.
  3. The next best way to pull data from an API is by building a URL from existing API documentation. This YouTube video explains how to pull location data from Google Maps via API, and then use those coordinates to find nearby photos on Instagram.

Overall, an API request doesn’t look that much different from a normal browser URL, but the returned data will be in a form that’s easy for computers to read. Here’s what happened when I requested information from the OpenWeather database in my web browser:

Example URL from documentation — request weather for a particular city:

api.openweathermap.org/data/2.5/weather?q={city name}

Type into your browser:

api.openweathermap.org/data/2.5/weather?q=Nashville,TN&APIID={numberslettersnumbersletters}

OpenWeather API responseConclusions and Further Reading

An API is useful for pulling specific information from another program. If you know how to read the documentation and write the requests, you can get lots of great data back, but it may be overwhelming to parse all of this. That’s where developers come in. They can build programs that display data directly in an app or browser window in an easily consumable format.

This article barely scrapes the iceberg that is API technology. I researched the web quite a bit to learn about APIs. These are the articles and videos that helped me the most:

Want to connect your programs, but don’t have the time to build a client? There are plenty of companies out there that will connect existing APIs or build custom connections for you. These can range from simple data-triggered apps like Zapier to full-scale business intelligence integrations that pull huge amounts of data from multiple sources for analysis. Knowing how an API works is the first step to building great integrations.