Understanding APIs and Data Exchange with JSON

What is an API?
An API (Application Programming Interface) is a tool that allows programs or systems to communicate with each other. Think of it like a restaurant scenario: a customer (client) places an order with a waiter (API), who then relays it to the kitchen (server) and returns the response (food). In software, APIs serve the same purpose by facilitating requests from one system to another.
APIs come in various types depending on their use case. Let’s explore some of these types and how they function.
Types of APIs and Their Functions
APIs can be categorized based on their usage or architecture into the following types:

RESTful API: Uses the HTTP protocol with methods like GET (retrieve data), POST (send data), PUT (update), and DELETE (remove). This type is common in web development due to its simplicity and flexibility.
SOAP API: Relies on XML for data exchange and is often used in enterprise systems like banking.
GraphQL API: Allows clients to request only the specific data they need, avoiding unnecessary information.
WebSocket API: Suitable for real-time, two-way communication, such as online chat applications.
Library-based API: Examples include internal APIs of programming languages, like JavaScript’s DOM API.

Each API uses specific formats to transfer data. Two common formats are JSON and XML, with JSON being widely observed due to its straightforward structure.
Data Exchange Formats: A Look at JSON
When a system sends a request to an API, the data must be formatted in a standard way. Some common formats include:

JSON (JavaScript Object Notation): Lightweight and readable, used in many projects.
XML (eXtensible Markup Language): More structured but heavier, common in older systems.
Other Formats: Such as YAML or Protocol Buffers, applied in specific cases.

Let’s take a closer look at JSON as a frequently used format.
What is JSON?
JSON (JavaScript Object Notation) is a format for exchanging data between systems. It uses simple key-value pairs and arrays, and is recognized for its simplicity and readability.
Features of JSON
JSON has characteristics that make it suitable for data exchange:

High Readability: Its structure allows users to understand the content at a glance. For example:

{
  "first_name": "Amir",
  "age": 25,
  "is_student": true,
  "hobbies": ["coding", "reading"],
  "address": {
    "city": "Tehran",
    "country": "Iran"
  }
}

In this structure, keys (like "first_name") are always strings, and values can take various forms.

Supported Data Types: JSON supports the following types:

String: Like "Amir"
Number: Including integers or decimals (e.g., 25 or 3.14)
Boolean: true or false
Array: Ordered lists like ["coding", "reading"]
Object: A collection of key-value pairs like { "city": "Tehran" }
Null: To indicate empty values

Note: JSON does not have a dedicated data type for dates; dates are typically stored as strings (e.g., "2025-09-09").

Compact Size: JSON lacks the additional tags found in XML, resulting in a smaller data size, which can be beneficial for data transfer.

JSON Syntax Notes

Keys must always be strings enclosed in quotes (").

Values can be unquoted (e.g., numbers or true).

Commas (,) are required after each key-value pair except the last one. For example:

{
  "name": "Amir",
  "age": 25
}

Adding a comma after "age": 25 causes an error, as JSON expects another key-value pair.

JSON in Practice
To illustrate, imagine sending user data to an educational system. A request might look like this:
POST /api/users HTTP/1.1
Host: example.com
Content-Type: application/json

{
  "user_name": "amir123",
  "email": "[e-mail]",
  "age": 25,
  "mobile": "[phone]"
}

The system’s response could be:

{
  "status": "success",
  "user_id": 1234,
  "message": "User created successfully"
}

Comparison with XML
Both JSON and XML are used for data exchange, but they differ:

JSON: Lighter and simpler, suitable for web development.

XML: More structured but heavier due to additional tags. Example:

<user>
  <first_name>Amir</first_name>
  <age>25</age>
</user>

XML remains in use in some older systems.
Limitations of JSON
While JSON has strengths, it also has limitations:

It does not support comments.
It lacks a data type for dates or times.
It is sensitive to syntax errors, such as extra commas.

Conclusion
APIs are tools for system communication, and JSON serves as one of the formats for data exchange, noted for its simple and readable structure. However, depending on the project’s needs, other formats like XML or YAML may also be utilized. For further details, exploring technical documentation related to APIs is recommended.