What is an API? Fully Explained with Examples

In this post I am going to explain what is an API, using a food outlet and a dictation app I have built for myself. I mostly work in PHP programming, but you don’t need to know PHP or any other programming language to follow the explanation.

First of all, API stands for Application Programming Interface. The name sounds technical. What it does is easier to understand through something we use every day.

What is an API? Start with a food outlet

An API is like the ordering counter at a food outlet. You don’t need to enter the kitchen or cook the food yourself.

You give the item name, say how much you want and make the payment. The item and quantity are the details, or parameters, you provide. The outlet prepares your food and gives it to you.

You need to know how to place the order at a food outlet, you don’t need to enter the kitchen and see how the food is cooked, and you don’t have to cook the food yourself.

When I describe an API this way, the counter is the part you interact with. The kitchen is the system doing the work behind it. The menu tells you what you can ask for. The food outlet is the API. The process that is happening inside the kitchen is the code of the API.

An API gives one program a way to ask another program for information or get something done. The program making the request follows a set of rules, and the receiving system processes it and sends a response.

Suppose a streaming service offered an API for finding titles added this month. Your website could send the month and country, then receive the matching titles and their details. You wouldn’t need access to the service’s entire database.

This is a hypothetical example. It would work only if the service provided that API and supported those filters.

You can also describe an API as a controlled way into a system. The owner decides which information and actions are available.

Most examples here concern web APIs, where programs communicate over a network. APIs also exist inside your computer, such as those a program uses to ask the operating system to open a file.

API explained through my dictation app and other examples

I have built a dictation app for personal use. I speak into it and it turns my speech into text.

But I haven’t built the system that recognises my speech. My app sends the audio to OpenAI’s Whisper API and receives text in return.

I have to buy credits to use the API, so running the app has an ongoing cost. I will come back to that.

What I find useful is that I could build a tool for my own needs without having to build the speech recognition system too. My code handles recording and sending the audio, then displaying the result.

The same idea applies to your website. A WordPress store can use the Stripe API through its WooCommerce extension to accept payments and process refunds.

You could also build a subscription form and use Mailchimp’s or Zoho Campaigns’ API to send the subscriber’s details to your mailing list. The API handles the connection to the mailing service; you still need the form on your website.

By the way, the subscription form that you see on my sidebar is using the Zoho Campaigns API.

There are familiar examples outside WordPress programming too. Shopify uses Stripe for Shopify Payments. Slack’s Google Drive connection lets people share files and receive comment notifications while the files remain in Drive.

So an API can fetch information, send information or ask another system to perform an action. It doesn’t have to involve a database lookup.

How API requests work: GET, POST and other methods

Let us stay with the food outlet.

Looking at the menu and placing an order are different actions. A web API needs to know which action your program wants to perform.

A request normally includes an address, called an endpoint, and a method that tells the API what you want to do. It may also include parameters, information in a request body and headers with details such as your access credentials.

These are the main HTTP methods:

GET: Retrieve Information

GET retrieves information without changing the requested record. At the food outlet, this would be asking, “Show me the menu.”

POST: Submit Information

POST submits information for processing, often to create a new record. At the food outlet, this would be placing an order for two sandwiches.

PUT: Replace a Complete Record

PUT replaces a complete record at a particular address. It can sometimes create a record too, if the API supports that. For example, you could replace your saved delivery address by sending the complete new address.

PATCH: Change Part of a Record

PATCH updates specific parts of an existing record. If only the postcode in your saved address needs changing, you could send that change while keeping the rest of the address as it is.

DELETE: Remove a Resource

DELETE removes a particular resource. At the food outlet, this could mean deleting a saved delivery address from your account.

HEAD requests the response headers without the body. OPTIONS asks about the communication options available. These methods have defined meanings, although each API decides which ones it supports at each address.

For example, a request could look like this:

GET /menu?added_month=2026-09

The part after the question mark is a query parameter. In this example it asks for items added in September 2026. The API must support that filter name.

For a new order, your program might send POST /orders, with the item name and quantity in the request body.

The response often uses JSON, a text format that arranges information into named fields and values. For example, the food outlet could return:

{
  
"orderId": 42,
  
"item": "Sandwich",
  
"quantity": 2,
  
"status": "accepted"
}

You can read this as: order 42 is for two sandwiches, and the outlet has accepted it. Text values go inside quotation marks, while numbers can appear without them. The curly brackets keep the fields together as one record.

My code could read the status and display “Your order has been accepted” on the website. JSON carries the information; my website decides how it should look. Other formats are possible too.

A response also includes a status code. For example, 201 can tell your program that a record was created, while 404 means the requested resource wasn’t found. Your code needs to handle errors as well as successful results.

Different types of APIs and building your own

APIs can be grouped by who can use them.

• Public APIs are offered to outside developers. Like a food outlet open to customers, they may still require registration and payment.
• Private APIs are used within an organisation. Think of the staff’s ordering screen that sends instructions to the kitchen.
• Partner APIs are shared with approved businesses. A delivery company might receive access to submit orders while other companies do not.

You will also hear names such as REST, SOAP and GraphQL. These describe different approaches to communication, rather than who gets access. Let me explain them through the same food outlet.

REST APIs

A REST API organises access around resources. A resource is simply something your program works with, such as a menu item, an order or a customer.

Suppose I am building an ordering website for a food outlet. To display the menu, my code sends GET /menu. When someone places an order, it sends POST /orders with the items and quantities.

The service creates the order and returns its number, say 42. My website can then use GET /orders/42 to check its status.

The address identifies the thing I am working with. The HTTP method tells the service what I want to do with it.

REST also expects each request to carry the information needed to understand it. For example, a request for a protected order would include the appropriate access credentials. The server can store orders, but it shouldn’t need to remember a previous conversation with my app to understand the next request.

This approach is useful when a website needs to read and manage records. The exact addresses and supported actions are decided by the API developer.

SOAP APIs and XML Messages

SOAP follows formal messaging rules and uses XML. XML arranges information between named opening and closing tags.

An order written in XML could look like this:

<order>
  <item>Sandwich</item>
  <quantity>2</quantity>
  <extraCheese>true</extraCheese>
</order>

The value between <item> and </item> tells the receiving program which item was ordered. The quantity is between its own pair of tags. So even without knowing XML, you can see that this order is for two sandwiches with extra cheese.

This is a simple XML example, not a complete SOAP message. SOAP puts the information inside an outer structure called an envelope, with a body containing the actual request or response.

At our food outlet, imagine a catering department that accepts orders only through a fixed form. Every partner knows which fields to fill in and how to submit them. If something is missing or incorrect, the department returns an error in an agreed format.

SOAP provides this kind of formal agreement between systems. Writing information in XML alone does not make an API a SOAP API.

GraphQL APIs

Suppose the food outlet stores a name, price, description, ingredients and photo for every dish. I am making a small menu panel that needs only the name and price of vegetarian items.

With GraphQL, I can specify those fields in my request. In an API designed to support this example, the query could look like this:

{
  
menu(category: "vegetarian") {
    
name
    
price
  
}
}

I am asking for vegetarian menu items, but only their names and prices. The response could look like this:

{
  
"data": {
    
"menu": [
      
{
        
"name": "Vegetable sandwich",
        
"price": 120
      
},
      
{
        
"name": "Paneer roll",
        
"price": 150
      
}
    
]
  
}
}

The square brackets hold a list of items. Each item has the two fields I requested.

This becomes useful when different screens need different details from the same system. A menu panel may need names and prices, while a dish page may also need ingredients and a description.

The API still decides which fields and filters are available. GraphQL does not let me ask for anything in the database. A REST API can also offer ways to select fields; GraphQL makes field selection part of its query language.

RPC and gRPC APIs

RPC stands for Remote Procedure Call. The focus here is on asking another system to run a named operation.

Suppose a customer wants to cancel order 42. An RPC request might call an operation named cancelOrder and provide orderId: 42.

At the food outlet, this is like calling the counter and saying, “Please cancel order 42.” Staff check whether it can still be cancelled, then tell you what happened. If preparation has already started, the request may be refused.

In programming terms, the operation runs on the other system. My code supplies the details and handles the result. The exact message format depends on the RPC API being used.

gRPC is a particular framework for building this kind of communication. Both programs use a shared definition of the operations and message fields. It commonly sends data in a compact binary format, which isn’t meant to be read like the JSON above.

For example, a food outlet’s ordering service could ask its stock service whether ingredients are available before accepting an order. gRPC also supports streams of messages, so it can handle a series of updates as well as a single request and response.

WebSocket APIs

Now suppose I want the customer’s order status to update on the screen as the kitchen works.

My website could repeatedly ask, “Is order 42 ready?” But if it asks every few seconds, many responses may say exactly the same thing.

A WebSocket connection gives the website and server an open connection through which either side can send messages.

The kitchen marks the order as accepted. The server sends that update. Later, it sends “Preparing”, followed by “Ready for collection”. My website displays each update when it arrives.

It is like staying on a call with the outlet. Staff can tell you something without waiting for you to ask again. Your website can also send messages through that connection, if the service supports them.

WebSocket is a communication protocol, rather than a complete set of ordering rules. The developer must still define what each message means, who may receive it and what happens if the connection drops. An open connection does not last forever.

Composite APIs and Webhooks

A composite API brings several operations into one request. For example, a lunch booking might need to check stock, reserve a delivery slot and create an order. The API coordinates those steps and reports the result. It still needs rules for what happens if one step fails.

A webhook works differently. Your system gives the food outlet an address where it can send a notification. When an order becomes ready, the outlet’s system sends a request to that address.

This is like leaving your number and asking the outlet to message you. Unlike WebSocket, a webhook does not require a continuously open connection. Webhooks are commonly used between servers.

These terms describe different parts of how systems work together. A private REST API, for example, could also send webhook notifications.

Building Your Own API

If you have wanted an API explained because you want to build one, you can start with PHP. I’m mentioning PHP because I mostly program in PHP.

Your PHP code can receive a request, check permissions, fetch information and return JSON. JavaScript on your website can request that information and display it. PHP programming can handle the server side without requiring a framework for a basic API.

In WordPress programming, you also have the built-in REST API. It provides access to content such as posts and pages, with permissions controlling protected operations. You can extend it with your own endpoints. If you check out my homepage, a few of my blog listings appear over there. The homepage template is using the WordPress REST API.

The important work is deciding what other programs may do. You need to validate requests, check access and keep database passwords and secret API keys on the server.

The benefits and limitations of using an API

For me, the main benefit is being able to build the part I need and connect it to a service that does the rest.

My dictation app would have been a very different project if I had also needed to build speech recognition. Using an API made the tool practical for my personal use.

APIs can also reduce manual work. A form submission can go into a mailing list without someone copying the details. Another program can request fresh information from your system without receiving direct database access.

And if the service changes its internal database while keeping its API the same, your program may continue working without changes.

But you depend on what the service provides.

• Cost: I have to buy credits for my dictation app. Other APIs may charge by request, usage or subscription.
• Request limits: A service may allow only a certain number of requests per minute or day.
• Missing features: You cannot request a filter or action the API doesn’t support.
• Availability: If the service is slow or unavailable, the part of your app that depends on it is affected.
• Data limits: Information may be delayed, restricted by region or returned in batches.
• Changes: The provider may remove a feature, change an API version or close the service.
• Usage rules: Getting access to information doesn’t automatically mean you can store or republish it however you want.

An API key also doesn’t give you unlimited access. The service still decides which information and operations your account may use.

So before building around an API, I need to know whether it supports the actual task, what it costs and what my program should do when a request fails. Those decisions are part of the programming work.

An API lets me use work that already exists. I still have to make the parts work together.