How to use an API: a tutorial for beginners!

From the comfort of my couch, I can easily accomplish a variety of tasks - ordering groceries, having food delivered, mapping the drive to Barnes & Noble, and checking the weather to determine if staying indoors is the best option. While some may view this as lazy, I consider it highly convenient. And I owe these conveniences to the power of APIs.

APIs, the crucial enablers of modern conveniences, are the glue that binds diverse applications together. These programming interfaces allow seamless communication and information sharing across different platforms, facilitating the integration that powers our daily lives. Moreover, APIs shoulder much of the complex backend work required for developing new applications, streamlining the creation of innovative digital tools and services.

I have compiled a detailed beginner's guide and tutorial on how to use APIs.

Table of contents:

• [What is an API?]
• [Why use an API?]
• [Getting started with APIs]
• [How to use an API]
• [REST vs. GraphQL vs. SOAP APIs]
• [Types of APIs]
• [API FAQ]

What is an API?

An API acts as a digital intermediary, allowing different software applications to communicate and share information with one another. It outlines the specific methods, parameters, and data formats that developers can use to access features or retrieve data from an application or online service.

Consider your go-to weather app - it taps into APIs to fetch real-time data from meteorological services and deliver that information straight to your device. Or think about using a social media login (like Facebook) to access another app - there are APIs working behind the scenes to securely authenticate your identity.

Why use an API?

Without APIs, we'd be stuck relying on old-fashioned paper maps to find our way around - and I'd probably get lost all the time. But APIs allow us to tap into existing data sources, rather than having to build everything from the ground up. For example, when you use a navigation app, it's sending requests through APIs to access real-time location data from cell towers and GPS satellites.

From a developer's perspective, APIs provide a valuable shortcut - they can leverage pre-built functionalities, allowing them to focus their efforts on creating new and innovative features. Take Planefinder, an app that tracks planes in real-time - rather than having to build their own mapping system from scratch, they used the Google Maps API. This freed them up to devote their time and resources to developing Planefinder's unique features and capabilities.

Using apidog, you can easily facilitate seamless integration between different systems, enabling smooth data exchange across applications. This integration capability proves invaluable when your business needs to share information across software platforms - like connecting your customer relationship management (CRM) system with your email platform. apidog is built on API technology to provide users with these convenient cross-system collaboration and data sharing capabilities.

Apidog is an API management platform that empowers seamless integration and smooth data sharing across your business systems. Through apidog's robust API capabilities, you can easily connect applications like your CRM and email platform, simplifying complex workflows and enabling valuable cross-system collaboration.

Getting started with APIs

I'll be throwing a lot of jargon your way, so before you get started, here are a few API terms you should get to know.

API keys

Much like a password, an API key is a unique string of letters and numbers that serves as an access code or authentication token. This key is required to access most APIs, as it is a critical security measure to track and control API usage. Just as you need a password to access your apps, you need a valid API key to access and utilize an API's data and functionality - ensuring only authorized users or applications can do so.

We'll cover how to obtain and use these keys in the next section.

API Endpoints

An API endpoint refers to a specific URL or web address that serves as the access point for an API, allowing it to communicate with another application. These endpoints act as standardized locations where requests are received and responses are sent back. They provide a clear and structured way for users to interact with an API's capabilities, much like the buttons on a vending machine.

Just as you select a particular snack by pressing a button on a vending machine, you can "press" an API endpoint by making a request to that specific URL. The API then knows exactly what information or action you're looking for and provides you with the corresponding response, delivering the digital "Snickers bar" you need.

Request methods

To communicate what you want to accomplish through an API endpoint, you'll need to make a request using one of four specific HTTP methods:

• GET: This method is used to retrieve particular data from the API.

• POST: This tells the API you want to add or post new data to the server.

• PUT: This method is for updating existing resources on the API.

• DELETE: As the name implies, this is used to remove existing data from the server.

These request types are also commonly referred to as CRUD - Create, Read, Update, and Delete. Many public-facing APIs will typically only allow GET (Read) requests, to prevent unauthorized parties from modifying their data. After all, you wouldn't want just anyone accessing a meteorology API and altering weather information.

API calls

An API call is the end-to-end process of making a request, having the API retrieve the data you need, and then receiving the corresponding response. All you have to do is make the request using one of the HTTP methods we covered earlier.

Think of it like ordering a drink at a coffee shop - you tell the barista what you want, they input your order into their system, and then hand you the finished beverage. An API call works in a very similar way, just without the caffeinated result.

Status codes

When you make an API request, you'll receive a status code - a 3-digit number that tells you if your request was successful or not. Codes starting with 2 mean your request worked. Codes starting with 4 mean there was a problem. These status codes let you know the outcome of your request.

How to use an API

I'll be using Apidog to show you an example of using an API. Apidog is a pretty accessible way to use APIs, that offer user-friendly interfaces for APIs.

1. Pick an API

There are thousands of public APIs available for use. You can search directories like GitHub or Google's API Explorer to find ones that interest you. Most sites will list their available APIs under an Advanced settings or Developers section, often at the bottom of the website.

I'll be using OpenAI API platform.

2. Consult the API documentation

Every API should provide you with documentation to get started. This will typically include a reference section detailing the available objects, parameters, and endpoints you can access. There are also often examples or "quickstart" guides expressed in popular programming languages, which explain:

• What functionalities the API offers
• Any dependencies or requirements for using the API
• How to actually utilize the API

And if the API requires an API key, you'll find that information in the documentation as well.

3. Write a request

Step 1: Create an OpenAI account
If you haven't already, go to the OpenAI platform, and create an account.

Step 2: Create a project (optional)

You're logged in. Before we move to grabbing our API keys, you can organize them by project if you'd like. This lets you collaborate with your team, set custom billing limits, and have better visibility over usage.

If you want to use this feature, on the top left of the screen, click Default project and then Create project. (You can also access the Organization overview page from here.)

Step 3: Create an OpenAI API key

Since the OpenAI API isn't free, you need to create an API key so the platform knows who you are and who to bill the work to. To generate an OpenAI API key, look to top-right side of the screen, and click Dashboard.

This is the OpenAI Playground that I mentioned before. It has all the tools for testing and developing with the OpenAI API. After you read the welcome message pop-up, you can click Get Started to continue.

Close the pop-up. On the left-side menu, click API keys.

On the top right of the screen, click Create new secret key. Note: you can only create an API key once you verify your account with your phone number.

A pop-up appears with your API key settings. I'll walk you through all of these in just a second.

Under Name, give your API key an appropriate name or service name ID.

If you created a project to manage your API keys, click the dropdown to select it. Otherwise, you can leave it on its default setting.

The last setting lets you adjust the Permissions this key has:

• All gives full access to all API features.
• Restricted lets you choose which models and tasks this key has access to. For example, if you're only using text generation, you can set Model capabilities to Write and all others to None.
• Read only blocks all writing requests, which is useful for pulling data into external systems.

Consider setting it to the lowest privilege level necessary to do what you need.

Once you've adjusted these settings, click Create secret key, and the platform will generate one for you. You won't be able to see this key again: copy and paste it to a safe place for now, and consider disposing of it after you've set up the call in the next step.

Once you click Done, the new key is added to the list. You can always delete or edit the name or permissions going forward.

Step 4: Open the API documentation and reference pages

Making and structuring the API call varies based on the API features that you want to use. To understand how to proceed, you need to find:

• The documentation page, which gives you a general overview of the API features and how to use them. Here's the documentation for the text generation feature.
• The API reference page, which includes all the technical specifications you need to pack into the request. Here's the API reference for the chat completions endpoint (we'll use it to run a text generation job).

Leveraging everything the API offers means you'll have to become familiar with these pages over time. Always remember to come back and read a bit more if you're running into trouble or brainstorming a new use case.

You can navigate back and forth between the documentation and API reference by using the links at the top right of the screen.

For this example, I want to use the chat completions endpoint, so I'm going to navigate to the corresponding page in the API reference. First, we need to copy the endpoint URL (https://api.openai.com/v1/chat/completions) and make a mental note of the HTTP method, which in this case is POST.

Step 5: Build a new request

You can use Apidog to send cURL requests. Apidogis a powerful API development and testing tool that offers a range of features and benefits to developers. Like Postman, Apidog allows users to send cURL requests, which is particularly useful for those already familiar with cURL in a terminal or command line interface. Leveraging Apidog’s user-friendly interface and numerous functionalities, you can create and send cURL requests alongside other types of requests with great ease. This enables developers to efficiently test APIs, quickly identify and debug potential issues, and maximize their API development workflows.

1. Through official documentation or access the OpenAI API project on Apidog, select the Chat Completions API endpoint from the left menu, and on the new request screen, enter the HTTP method and endpoint URL according to the ChatGPT specification. Then, in the “Body” tab, write the message you want to send to ChatGPT in JSON format.

2: Switch to the “Header” tab, add the Authorization parameter to authenticate with the ChatGPT API, enter the ChatGPT API key you obtained, and click the “Send” button.

Note: In Apidog, you can store your OpenAI API key as an environment variable. Storing the OpenAI API key as an environment variable means you can directly reference the environment variable later without having to re-enter the API key repeatedly, which is convenient.

REST vs. GraphQL vs. SOAP APIs

• A REST (representational state transfer) API, or RESTful API, is the most common form of API today. It's web-based, meaning the information is exchanged online. When you make a request with a REST API, you'll receive all of the data available from the API.
• GraphQL (query language) APIs work in a similar fashion, except they only fetch and respond with the specific data you want instead of getting all of it. So you can specify the fields you want and avoid large data exchange and a subsequent load speed headache. GraphQL APIs are fairly new to the scene and therefore not as common, but are growing in popularity.
• SOAP (simple object access protocol) APIs use XML (extensible markup language), a type of programming language, to communicate. They were the standardized approach for communicating between different software applications in the early 2000s. They've significantly declined in popularity since then, as they're more complex and inflexible compared to alternatives like REST and GraphQL.

Types of APIs

There are four ways APIs are categorized, each with its own users and privileges.

Open APIs

These are public APIs that let developers access the platform's services or data. They're also accessible for third-party integrations. Here are some examples:

• Google Maps API: Anyone can use this API to integrate Google Maps into their apps to provide access to mapping and location-based services.
• Notion API: This open API allows users to connect Notion workspaces with other software.
• OpenAI API:** This API lets developers connect the GPT-4o API and the Whisper API with other apps.
• Discord API: Discord channels can be integrated with external apps using this API.

Partner APIs

This is a type of API created for partners or selected third-party entities. They provide restricted access to certain functionalities or data, often for integration between the platform and its partners. Here are a few examples:

• Facebook Login API: Third-party applications can use this API to enable user authentication with Facebook credentials for an easy login experience.
• Airbnb Partner API: Prospective partners will be personally contacted by Airbnb's partner managers to implement this API, which integrates external booking and other systems.
• eBay APIs: eBay offers a number of APIs to users who join the eBay Developers Program, including Sell APIs, Buy APIs, Commerce APIs, and more.

Internal APIs

These are also known as private APIs, and they're created and used by an organization for internal purposes. They facilitate communication and data sharing between internal systems. Because these are part of private or proprietary processes, they aren't generally public knowledge. Here's one example:

• Amazon API: Amazon employees share data exclusively through their internal APIs, helping them scale over the years.

Composite APIs

Also referred to as orchestration APIs, composite APIs consolidate data or functionalities from multiple APIs. They act as a single entry point for clients and simplify the complexity of interacting with multiple APIs with a unified interface. Here are a couple of examples:

• Twilio API: This API integrates multiple communication channels, allowing users to build comprehensive communication solutions.
• Salesforce Composite API: This API executes multiple Salesforce API requests in one call.

APIs open up endless opportunities to create innovative applications and services. But if you just want to use APIs to integrate your apps or automate your workflows.

API FAQ

Like anything involving code, data, and servers, APIs can be hard to wrap your head around if you're not a developer. But if you've made it this far, you're in good shape. For answers to lingering questions, read on.

How do I access data from APIs?

APIs are used to access data from a server or servers without making the user go searching for it. But if you want to look at the data more closely (i.e., see the Matrix), you'll likely need developer access to your chosen API.

What are the 4 types of APIs?

The four most common types of APIs are open, partner, private, and composite. Open APIs are accessible to the general public. Partner APIs are only accessible to select users or teams. Private APIs are used by companies internally. Composite APIs bring multiple APIs together in one unified interface.

What is an API?

APIs are application programming interfaces that connect different apps, allowing them to communicate and exchange data. If you use a phone or a computer (which you do), you likely interact with APIs all the time without realizing it.

If you want to implement one yourself, you'll first need to find a public API and brush up on your coding knowledge.