Introduction to APIs

By the Syncfusion DevTutorials team · Last updated October 20, 2026

Learn what an API is, how a client and a server talk through requests and responses, and why every API is a contract. Break one and fix it in your browser.

An API (Application Programming Interface) is a way for one program to communicate with another program over a network. The program that sends a request is called the client. The program that receives the request and sends back a response is called the server. An API acts as a bridge between them. It defines the rules for what the client can ask for and what the server will return. These rules are called the API's contract.

Watch an App Break

Every lesson in this course starts the same way. A client app breaks. Then you change the API, and the app works again. Here is the first example. The Brew & Bytes coffee shop has a mobile app that shows the menu. Yesterday it worked. Today the server team changed one word in the server response, and now look at the screen.

The prices are still there, but the names are missing. Nobody changed the app. Now untick Rename the field name → title, and the names appear again.

In simple words: the app and the server agreed on what the response should look like. The server changed that agreement, so the app stopped working correctly. This agreement is called the API contract.

TL;DR

• An API is how one program asks another program for something.
• The program that asks is the client.
• The program that answers is the server.
• The client sends a request.
• The server sends a response.
• An API is a contract. It defines which requests the server accepts and what responses it returns.
• The client only knows the contract. It does not know the server's internal code.
• You can change the server's code freely.
• You must change the contract carefully.
• Before making any change, ask: Will this break any existing client?

A Real-World Example

Think about ordering food in a restaurant. You sit at a table. You do not go into the kitchen. You tell the waiter, "One latte, please." The waiter takes your order to the kitchen. After a few minutes, the waiter brings you a latte. You never see how the kitchen works. The restaurant may use a new machine or a different cook. It does not matter to you. You only care that you asked for a latte and received a latte.

Now compare this to software:

If you ordered a latte but received tea, you would be unhappy because the restaurant broke its promise. The same thing happens when an API changes its response without warning. Apps that depend on it can stop working.

What You Will Learn

In this lesson, you will learn:

1. What an API is and why programs use it.
2. What a client, server, request, and response are.
3. Why an API is a contract.
4. Why server code can change freely but the contract must be changed carefully.
5. How files are organized in a real API project.
6. The request journey used throughout this course.

How an App Talks to a Server

The Client and the Server

A client is the program that asks for something. In our example, the Brew & Bytes mobile app is the client. A server is the program that responds. It runs on another computer and stores information such as menus, customers, and orders.

The client and server are separate programs. They may even be built by different teams using different programming languages. They can still communicate because they follow the same API contract.

One Request, One Response

A request is a message sent from the client to the server. For example: "Give me the menu." A response is the server's reply. It contains information about the result and may include data.

Press Play below and watch a request go to the server and a response come back. Use Step to move through the conversation one message at a time. The panel on the right shows the exact text of each message.

Look at the response. It contains three parts:

• Status code: 200 OK. This tells the client what happened. 200 means the request succeeded.
• Content type: application/json. This tells the client the type of data being returned.
• Body: The actual menu data written in JSON format.

JSON is a text format used to represent data.

• [ ] represents a list.
• { } represents an object.
• Fields are written as key-value pairs such as "name": "Latte".

Most modern APIs use JSON.

Run the Conversation Yourself

The next example is a real Brew & Bytes API.

• In C#, the code is a complete ASP.NET Core Program.cs. app.MapGet("/menu", ...) means that when a GET /menu request arrives, this code runs. app.Run() starts the application.
• In React + TypeScript, the code is a complete Hono server.ts. app.get("/menu", ...) means that when a GET /menu request arrives, this code runs. export default app makes the application available to the runtime.

Press Run.

The response shows the status 200, the content type application/json, and the body, which is the menu data as JSON text.

Try changing the request from GET /menu to GET /drinks, and run it again. Because /drinks does not exist, the server returns: 404 Not Found

Now the client uses that JSON text. It converts the JSON into data and reads the name and price fields.

This is exactly what the mobile app does. The app does not know how the server got the menu. It only knows that each item contains a name and a price.

An API Is a Contract

What the Contract Says

A contract is a promise. The contract of the API says two things:

1. What you can send. For example: GET /menu.
2. What you will get back. For example: 200 OK, and a list of items. Each item has an id (a number), a name (text) and a price (a number).

The contract is everything that the client can see: the address that it calls, the status codes, the field names and their types. Everything else is the implementation: the classes, the database, the framework. The client cannot see those.

Here is a short way to remember it:

Check a Reply Against the Contract

A contract is not just a nice idea. A program can check it. The next box checks four replies. It looks for each field that the contract promises, and it checks the type of the field.

Look at the last line. Adding a new field, size, did not break the contract. The app still finds id, name and price. It ignores the extra field. Adding is usually safe. Renaming and removing are not safe.

Change the Code Freely, the Contract Carefully

Swap the Menu Store, Keep the Promise

Here, the server keeps its menu in a menu store. There are two stores. One keeps the menu in a list. The other keeps it in a dictionary, which is looked up by id. The code inside is different. The reply is the same.

• In C#, the endpoint asks for IMenuStore. An interface is a promise about which methods a class has. The line builder.Services.AddSingleton<IMenuStore, DictionaryMenuStore>() picks the store. Run the box. Then change DictionaryMenuStore to ListMenuStore and run again. The reply is exactly the same.
• In React + TypeScript, the route asks for a MenuStore. An interface is a promise about which methods a class has. The line const store: MenuStore = new MapMenuStore() picks the store. Run the box. Then change it to new ListMenuStore() and run again. The reply is exactly the same.

The app cannot tell which store answered. You changed the implementation, and no client broke. Try it in the lab above too. Switch Menu store. The phone still shows the full menu.

Rename One Field, Break Every App

Now the wrong way. The server team thinks that title is a nicer word than name. They rename the field. The code of the app stays the same, because the app is already installed on thousands of phones.

The status is still 200. The server thinks that everything is fine. But look at the body. It now says "title":"Latte". Renaming one field of MenuItem changed the JSON. The app still looks for name, and it finds nothing. Every name on the phone is now blank.

Sending Data to an API

So far, the app only asked for data. An API also lets a client send data. Here Asha orders two lattes. The client sends the order in the body of the request. The server saves it and replies.

This time, the status is 201, not 200. 201 means "created": the server made something new, which is an order with id 101. The reply also has a Location header: the address of the new order, /orders/101. You will learn all the common status codes in a later lesson. For now, notice that the response tells the client what happened.

What It Looks Like in a Real Project

The boxes above put the client and the server in one small program, so that you can see both at once. A real API keeps them in separate projects, and each job has its own file. Click through the files below. It is the same menu API, laid out in the way that you would build it at work.

Each file has one job:

The contract lives at the endpoint or route: the address /menu and the shape of the reply. The service can change completely, and no app will notice, as long as the endpoint keeps sending the same shape.

The Journey of a Request

Every request in this course follows the same trip. It leaves the client. In bigger systems, it passes a gateway, which is a front door that checks every request. It reaches your API. Your API talks to a database, where the data is stored. Then the response travels all the way back.

This picture is the map for the whole course. When a client breaks, the first question is: at which stop did it break? Each lesson teaches the fix for one stop. This lesson is about the band at the top: the contract that wraps the whole trip.

Where APIs Are Used

APIs are everywhere. A single app often uses many of them. Think about ordering food on your phone:

• The API of the restaurant gives the menu and takes the order.
• A payments API charges your card.
• A maps API shows where the rider is.
• A messages API sends "Your food is here."

Each company builds its API once. Many apps use it. That only works because each API keeps its contract.

Common mistakes

Exercises

What to Remember

• An API lets one program ask another for something. The client asks with a request. The server answers with a response.
• An API is a contract: what you can send, and what you get back.
• The client only sees the contract. Change the code of the server freely. Change the contract carefully.
• Adding a field is usually safe. Renaming or removing one breaks apps, even when the server still says 200 OK.
• Before every change, ask: does any existing client break?

Next: HTTP Basics. You will read every line of a real request and response, and build one by hand.