What Is an API? REST APIs Explained Simply

01What Is an API? The Waiter Analogy

The best-known way to explain what an API is is the restaurant analogy. You are the customer, and the kitchen is the system that holds the data. You cannot walk into the kitchen yourself; you look at the menu and give your order to the waiter. The waiter passes the request to the kitchen and brings you the finished dish. In this scenario, the waiter is the API.

The menu is the API's documentation: it tells you what you can ask for, how to ask and what you will get in return. You cannot ask for something that is not on the menu, and you do not need to know how the kitchen works.

In the software world, this arrangement is a big convenience. An e-commerce site does not need to know the internals of a shipping company's system; it tells the shipping company's API “create a label for this shipment” and receives the response. Both sides can change their internals as long as the API contract is kept.

02What Is an API Used For?

The answer to what an API is used for is hidden in almost every digital service you use daily. Picking a location on a map on a site, paying by card, signing in with Google or seeing the weather is an API call behind the scenes.

• Connects systems: the website, marketplace, shipping, accounting and payment systems work in a single flow.
• Reduces manual data entry: order, stock and invoice information passes from one system to another automatically.
• Feeds mobile apps: the app on a phone gets data not directly from the database but through the API.
• Lets you use ready-made services: you do not have to write payment, map, SMS or email infrastructure from scratch.
• Provides secure access: only permitted operations are exposed to the outside party, not the entire database.

03What Is a REST API?

APIs can be designed in different styles; the most common on the web is the REST approach. The short answer to what a REST API is: an API style that uses the HTTP protocol, identifies each piece of data with an address (a resource) and performs operations on these resources with standard methods.

In REST, everything is a resource: products, orders, customers. Every resource has an address, and which HTTP method you use at that address determines what you want to do. Responses mostly come back in JSON format, a text format that is both human-readable and easy for programs to process.

What Is an Endpoint?

An endpoint is the address in an API where a specific operation is performed. For example, /api/urunler is the endpoint for the product list and /api/urunler/42 is the endpoint for product number 42. An API's documentation is essentially a list of these endpoints, the methods they are called with and what they return.

Status Codes

Every response comes with an HTTP status code that summarizes the outcome. 200 means success, 201 record created, 400 bad request, 401 not authenticated, 403 no permission, 404 not found, 429 too many requests and 500 server error. A good integration handles each code separately.

04What Does an API Request Look Like?

An API request basically has four parts: the address, the method, headers (credentials, data type) and, if needed, a body (the data sent). Below you can see a simple read request to a public test API and a typical JSON response.

You can send this request from the terminal with curl, from the browser with JavaScript, or on a server with Python or Node.js; the rules are the same, only the tool changes.

curl -s https://jsonplaceholder.typicode.com/posts/1 \
  -H "Accept: application/json"

{
  "userId": 1,
  "id": 1,
  "title": "...",
  "body": "..."
}

const yanit = await fetch("https://jsonplaceholder.typicode.com/posts/1");
if (!yanit.ok) throw new Error(`Hata: ${yanit.status}`);
const veri = await yanit.json();
console.log(veri.title);

05API Security and Authentication

Apart from public test APIs, you cannot access a real API without proving who you are. The most common methods are API keys, short-lived access tokens and authorization flows such as OAuth.

Security is not just authentication. A well-designed API gives each user only the permissions they need, validates incoming data and limits the number of requests (rate limit) to prevent abuse.

• Never put API keys in code that is sent to the browser or in a public repository.
• Always make the connection over HTTPS.
• Store keys in environment variables and rotate them regularly.
• Request only the permissions you need; if read access is enough, do not ask for write access.
• Do not leak internal system details in error responses.

06API Integration Examples

API integration is connecting two or more systems through their APIs so that they exchange data regularly and automatically. Almost all of these connections can be seen in the daily flow of an e-commerce business.

When an order arrives, stock is updated on every channel where the product is sold; this is done through marketplace integration. When the order is confirmed, a label and tracking number are obtained from the shipping company; this step falls under shipping integration. The invoice is issued automatically and sent to the customer through e-invoice integration (Turkish e-invoicing).

In all of these connections, the hard part is not making the first call. The answers to questions such as what happens when the other system does not respond, how to prevent the same order from being processed twice and who gets notified when something fails are what separate a solid integration from a fragile connection.

API or Webhook?

With an API, you ask and the other side answers. With a webhook, the other side notifies you on its own when an event happens. Instead of constantly asking “is there a new order?”, getting a notification when an order arrives is often more efficient; details are in our What is a webhook article.

07Where Do You Start with API Development?

To learn to use an API, a good start is to pick a public test API and send requests with curl or an API testing tool. Reading the responses, interpreting status codes and trying out error cases quickly cements the concepts.

If you want to write your own API, you need to choose a back-end language. For a quick and readable start, see the FastAPI example in our What is Python article; if you want to go the JavaScript route, see the Express example in our What is Node.js article.

In every case, a good API has three common traits: clear and up-to-date documentation, consistent naming and predictable error responses. If a developer who will use an API can read the documentation and make their first request within minutes, the design is on the right track.