In Module 1, we got a solid grasp on what APIs are, we are ready to look deeper into how these two communicate. Let's delve into the mechanics of API protocol. 

Whether it’s streaming with Spotify and Netflix, paying with Stripe, searching for the weather, logging in with Facebook, or interacting with a Twitter bot, all of these rely on APIs to deliver power and flexibility.

The best way to understand API is to get some experience, and this is what this module will cover.

APIs can be written and consumed in almost any server-side language. One computer has to put the data in a format that the other will understand.

APIs will generally return one of two types of data formats: JSON (JavaScript Object Notation) and XML (Extensible Markup Language).

Extensible markup language (XML)

XML is a simple and flexible text format used for data storage and exchange. It defines a set of rules for encoding documents in a self-descriptive format, which makes them easily readable.

When submitting XML calls through the API, make sure that the post content-type is set to application/xml.

XML provides simple building blocks that structures data. The main block is called a node which wraps every item in XML. The Node object is the primary data type for the entire DOM.

A node can be an element node, an attribute node, a text node, or any other of the node types. The name of each node tells us the attribute and the data inside is the actual detail.

Let's see what a message might look like in XML:

XML always starts with a root node, which in our example is "node". Inside the node are more "child" nodes.

You can use an XML validator to perform a syntax check of your XML. To validate a simple XML file using W3schools XML Validator, here's a sample we can use to syntax-check.

Copy and paste the XML file below into the text area on w3schools.com/xml/xml_validator.asp:

Errors in XML documents will stop your XML applications. If errors are found, they are highlighted in the text with the error described in a popup window.

With this code, there are no errors found. Now let's try this again with some minor adjustments. Note that XML tags are case-sensitive:

You can also generate XML output from a JSON data source using encoding, namespaces, fields, and attributes.

JavaScript Object Notation (JSON)

JSON is a way of representing data like XML.

JSON is a lightweight and easy-to-parse text format for data exchange. Its syntax is based on a subset of the Standard ECMA-262 3rd Edition. JSON is built on the popular Javascript programming language, usable on both the front-end and back-end of a web app or service. Due to its universal data structures that can be used with any programming language, many new APIs have adopted JSON as a format.

Like XML, JSON provides simple building blocks to structure data. JSON's very simple format has two pieces: keys and values. Each JSON file contains collections of name/value pairs and ordered lists of values. Keys represent an attribute about the object being described.

Let's see how our previous XML message could look in JSON:

In the JSON example above, the location (object) has attributes (keys), which are the words on the left: name, address, and status. They tell us what attributes the address contains. These attributes have corresponding values which are the parts to the right. These are the actual details of the address (Hubert street 12, Keynes, and Alabama).

Sometimes you want to use an object as the value for a key. Let's extend our location information with the property owner details:

We can see what this looks like when it is updated with a new key owner. Nested in this key is another set of keys (name, phone) and values (Jimmy, 777-123-4567) that provide details about the owner of the property.

Easy-to-read Best Buy JSON trees with Postman

When using APIs and getting results in JSON format. The way the browser displays the information may be hard to understand. This is why we'll use a tool to interact with APIs. You can use graphical user interface (GUI) REST clients to make the requests and test with REST APIs.

The popular graphical user interface (GUI) client we're using is Postman. Postman is an API test tool that simplifies each step of the API lifecycle and streamlines collaboration, without having to perform many unnecessary steps. It is free, allows you to save both calls and responses, and works on both Mac and PC. Postman comes with support for JSON and JSONP, regardless of the URL, and allows sending HTTP requests to a server and reviewing the responses.

Now let's try to interact with Best Buy API.

Open your browser and input some search criteria on bestbuy.com. You can easily input a search for all flat-panel TVs with prices and sorts by the best-selling products over the last week, and you will be given a list of products available for the request.

If we want to integrate this search data somewhere else, you will need to have access to Best Buy's API. This is where the concept of public, private and partner APIs come in. Some companies provide open access to their data while others don't. In this case, Best Buy does have API Documentation.

The base URL is https://api.bestbuy.com/v1. The Base URL is the base address for the specific API.

We’ll use Postman to make a request using Best Buy's API. To make the request, create an account or sign in at https://www.postman.com/. Next, click Create a request.

Best Buy has a collection of sample queries in Postman that’ll help you get up to speed with their APIs faster. To start using the API, you need to GET API Key. After you activate your key, you can start accessing Best Buy’s data.

Click the Run in Postman button on the website:

This redirects you to your Postman workspace to import the collection and environment.

Post this request URL in Postman and click the Send button

curl 'https://api.bestbuy.com/v1/products(categoryPath.name="All%20Flat-Screen%20TVs")?format=json&show=sku,name,salePrice&sort=salePrice&apiKey=YourAPIKey'

Now, take a look at the organised JSON response you get with Postman. It is an easy-to-read format we can understand, differentiating different attributes and values accordingly.

Postman takes the response and makes it easier to read and understand.

Notice that the request URL contains some Query Parameters similar to the key and value explained in the previous module. This makes it easy to either enable or disable the keys or edit the values. Postman allows you to write Query parameters as well. The address gets updated as these changes are made so when resubmitting this request, you will get a different dataset.

Query parameters are a defined set of parameters attached to the end of a URL.

When you enable or disable these parameters, they appear as a query string to the endpoint URL in the GET box. 

For example, your endpoint will now look like this: https://api.bestbuy.com/v1/products(customerTopRated=true&categoryPath.id in(abcat0205004))?apiKey={{apiKey}}&format=json&pageSize=10&show=sku,name,image,salePrice,customerTopRated&sort=bestSellingRank. 

Query string parameters appear after the question mark ? symbol and are separated by ampersands &.

Let's go back to the Best Buy documentation to understand what is possible. The documentation makes reference to different addresses.

We've used /products to indicate the desired response format with the extension. /stores return a collection of stores while /categories returns a collection of categories. These different addresses are called Endpoints.

When an API interacts with another system, the touchpoints of this communication are considered endpoints. The endpoint comes right after the base URL.

Endpoints are the URLs that enable the API to gain access to resources on a server. Most APIs have different endpoints with their own end paths.

When testing endpoints with different parameters, you can use Postman as a GUI REST client to make the requests and test with REST APIs. It's typical for APIs to have different endpoints which provide multiple views of the data.

The Bannerbear API is primarily asynchronous. Each endpoint is the location from which the API can access the resources they need to carry out its function.

If you are writing your own application within Postman, you can display the data from the API by copying the code and pasting it into the Test tab within the request, pasting it, and sending it. This way you can format the type of data you want.

Although Postman is a popular REST client, you can also use others to test and describe the APIs, such as Paw for Mac.

Like Postman, Paw also allows you to easily see the request headers, response headers, URL parameters, and response in an expandable/collapsible way. With Paw you can compose requests, inspect server responses, generate client code, and export API definitions.

API Security

APIs create an added layer of protection between your data and a server. An API gateway can limit access to minimize security threats.

API offers security by design because its position as the middleman facilitates the separation of functionality between the consuming application and the infrastructure providing the service. During the exchange, the API endpoint, HTTP headers, cookies, and query string parameters provide additional security layers to the data.

Developers strengthen API security by using access tokens and signatures. Implementing API gateways with Transport Layer Security (TLS) encryption ensures protection from being able to see what you transmit particularly with private and sensitive information. 

Authentication with API Keys

Before you can start using APIs, you need an API key to perform some action.

Most APIs are secured with API Keys. API Keys are unique identifiers, made up of a string of letters and numbers, used as authentication credentials to access an API. An API key and access token serve the same purpose. 

There are several techniques APIs use to authenticate a client. API calls usually include authorization credentials to reduce the risk of attacks on the server. 

When you register an account on a website, the site asks you for some personal information. The username/email and password provided are your credentials which you can use to log in when you visit the website again. This is the most basic form of authentication, called Basic Authentication, or Basic Auth.

When the client authenticates with the API key, the server knows to allow the client access to data. When you click the buy button on an e-commerce website, the app sends a request to the server notifying you of a user's desire to make a purchase.

Open Authorization (OAuth) is also a widely used authentication scheme on the web. OAuth is an authorization protocol that enables apps to access information on behalf of users.

Now we can consolidate everything that we learned together and guide you through how to use API practically.

📎 PREVIOUS MODULE - API 101: Introduction to APIs

📎 NEXT MODULE - Make API Calls: Introduction to Restful APIs

ABOUT ME

I'm Juliet 'Hiri' Edjere, a no-code expert focused on design, business development, and building scalable solutions with minimal coding knowledge.

I document all things product stories, MVP validation, and how designs, data, and market trends connect to one another.

In our world where innovation knows no boundaries, and creativity reigns supreme, no-code is a game-changer in today's tech landscape. Whether you're a developer looking to expand your skill set or a beginner curious about creating without writing a single line of code, you will learn from practical examples, and explore the possibilities of no-code technology. Together, we'll navigate the tools, platforms, and strategies – one blog post at a time!

Visit my website →