DEV Community: Amirmohammad Kazemi

JSON files in C++ (RapidJSON)

Amirmohammad Kazemi — Tue, 21 Jan 2025 14:52:22 +0000

A JSON file (short for JavaScript Object Notation) is a lightweight, human-readable text format used for data exchange. It is commonly used to transfer data between a server and a client and is highly popular due to its simplicity and readability. JSON uses a key-value pair structure and supports data types such as strings, numbers, arrays, objects, and boolean values.

General Structure of JSON:

Data is written as key-value pairs.
Keys must be enclosed in double quotes (").
Values can be strings, numbers, arrays, other objects, true, false, or null.
Key-value pairs are separated by commas (,).
Objects are enclosed in curly braces ({}).
Arrays are enclosed in square brackets ([]).

Simple Example of a JSON File:

{
  "name": "John Doe",
  "age": 30,
  "isStudent": false,
  "address": {
    "street": "123 Main St",
    "city": "Anytown",
    "state": "CA"
  },
  "phoneNumbers": [
    {"type": "home", "number": "123-456-7890"},
    {"type": "work", "number": "987-654-3210"}
  ],
  "email": "john.doe@example.com"
}

Explanation of the Example:

name: A key with a string value ("John Doe").
age: A key with a numeric value (30).
isStudent: A key with a boolean value (false).
address: A key with an object value containing address information.
phoneNumbers: A key with an array value containing two objects. Each object includes the type of phone number (type) and the phone number itself (number).
email: A key with a string value ("john.doe@example.com").

Uses of JSON:

Data Storage: For example, in configuration files or temporary data storage.
Data Exchange: For instance, in APIs, data is often exchanged between servers and clients in JSON format.
Software Configuration: Many software applications use JSON to store settings.

Another Example (An Array of Objects):

[
  {
    "id": 1,
    "name": "Alice",
    "email": "alice@example.com"
  },
  {
    "id": 2,
    "name": "Bob",
    "email": "bob@example.com"
  }
]

In this example, there is an array of two objects, where each object contains information about a user.

JSON is a highly flexible and simple format that can easily be used in most programming languages such as JavaScript, Python, Java, C#, and more.

Get start with RapidJSON

To work with JSON files in C++, there are several libraries available, and one of the most popular is RapidJSON. RapidJSON is a fast and lightweight library for processing JSON in C++. Below is a comprehensive explanation of how to use RapidJSON to work with JSON files.

Steps to Use RapidJSON in C++

1. Installing RapidJSON

First, you need to add RapidJSON to your project. There are two main ways to do this:

Direct Download: Download the library files from the official RapidJSON GitHub page and add them to your project.
Using a Package Manager (e.g., vcpkg): If you are using vcpkg, you can install RapidJSON with the following command:

  vcpkg install rapidjson

2. Adding RapidJSON to Your Project

After downloading or installing RapidJSON, you need to include its header files in your project.

#include "rapidjson/document.h"
#include "rapidjson/writer.h"
#include "rapidjson/stringbuffer.h"
#include <iostream>
#include <fstream>

3. Reading and Parsing a JSON File

To read and parse a JSON file, follow these steps:

Example: Reading a JSON File

Assume you have a JSON file named data.json with the following content:

{
  "name": "John Doe",
  "age": 30,
  "isStudent": false,
  "address": {
    "street": "123 Main St",
    "city": "Anytown",
    "state": "CA"
  },
  "phoneNumbers": [
    {"type": "home", "number": "123-456-7890"},
    {"type": "work", "number": "987-654-3210"}
  ]
}

C++ code to read and parse this file:

#include "rapidjson/document.h"
#include "rapidjson/istreamwrapper.h"
#include <fstream>
#include <iostream>

int main() {
    // Open the JSON file
    std::ifstream ifs("data.json");
    if (!ifs.is_open()) {
        std::cerr << "Failed to open file!" << std::endl;
        return 1;
    }

    // Read and parse the file
    rapidjson::IStreamWrapper isw(ifs);
    rapidjson::Document doc;
    doc.ParseStream(isw);

    // Check for parsing errors
    if (doc.HasParseError()) {
        std::cerr << "Parse error: " << doc.GetParseError() << std::endl;
        return 1;
    }

    // Access JSON values
    const std::string name = doc["name"].GetString();
    int age = doc["age"].GetInt();
    bool isStudent = doc["isStudent"].GetBool();

    const std::string street = doc["address"]["street"].GetString();
    const std::string city = doc["address"]["city"].GetString();
    const std::string state = doc["address"]["state"].GetString();

    // Print values
    std::cout << "Name: " << name << std::endl;
    std::cout << "Age: " << age << std::endl;
    std::cout << "Is Student: " << (isStudent ? "Yes" : "No") << std::endl;
    std::cout << "Address: " << street << ", " << city << ", " << state << std::endl;

    // Access arrays
    const rapidjson::Value& phoneNumbers = doc["phoneNumbers"];
    for (rapidjson::SizeType i = 0; i < phoneNumbers.Size(); i++) {
        const std::string type = phoneNumbers[i]["type"].GetString();
        const std::string number = phoneNumbers[i]["number"].GetString();
        std::cout << "Phone Type: " << type << ", Number: " << number << std::endl;
    }

    return 0;
}

4. Creating and Writing a JSON File

To create a new JSON file and write data to it, follow these steps:

Example: Creating a JSON File

#include "rapidjson/document.h"
#include "rapidjson/writer.h"
#include "rapidjson/stringbuffer.h"
#include <fstream>
#include <iostream>

int main() {
    // Create a Document object
    rapidjson::Document doc;
    doc.SetObject();

    // Add values to the Document
    rapidjson::Value name("John Doe");
    doc.AddMember("name", name, doc.GetAllocator());

    doc.AddMember("age", 30, doc.GetAllocator());
    doc.AddMember("isStudent", false, doc.GetAllocator());

    // Create an object for the address
    rapidjson::Value address(rapidjson::kObjectType);
    address.AddMember("street", "123 Main St", doc.GetAllocator());
    address.AddMember("city", "Anytown", doc.GetAllocator());
    address.AddMember("state", "CA", doc.GetAllocator());
    doc.AddMember("address", address, doc.GetAllocator());

    // Create an array for phone numbers
    rapidjson::Value phoneNumbers(rapidjson::kArrayType);

    rapidjson::Value phone1(rapidjson::kObjectType);
    phone1.AddMember("type", "home", doc.GetAllocator());
    phone1.AddMember("number", "123-456-7890", doc.GetAllocator());
    phoneNumbers.PushBack(phone1, doc.GetAllocator());

    rapidjson::Value phone2(rapidjson::kObjectType);
    phone2.AddMember("type", "work", doc.GetAllocator());
    phone2.AddMember("number", "987-654-3210", doc.GetAllocator());
    phoneNumbers.PushBack(phone2, doc.GetAllocator());

    doc.AddMember("phoneNumbers", phoneNumbers, doc.GetAllocator());

    // Convert Document to a JSON string
    rapidjson::StringBuffer buffer;
    rapidjson::Writer<rapidjson::StringBuffer> writer(buffer);
    doc.Accept(writer);

    // Write the JSON string to a file
    std::ofstream ofs("output.json");
    if (!ofs.is_open()) {
        std::cerr << "Failed to open file for writing!" << std::endl;
        return 1;
    }
    ofs << buffer.GetString();
    ofs.close();

    std::cout << "JSON file created successfully!" << std::endl;
    return 0;
}

5. Compiling and Running

To compile the program, you need to link RapidJSON to your project. If you are using g++, run the following command:

g++ -o json_example json_example.cpp

Then, run the program:

./json_example

Important Notes:

Memory Management: RapidJSON uses an allocator for memory management. When adding values to a Document, always use the allocator.
Error Checking: Always check for parsing errors to avoid program crashes.
Code Readability: For complex JSON structures, break your code into smaller functions to improve readability.

Using RapidJSON, you can easily work with JSON files in C++. It is a fast and efficient library, suitable for both small and large projects.

Advance use

Yes, RapidJSON has many more methods and features that allow you to work with JSON in more advanced ways. Below, we explain some of the key methods and features of RapidJSON with examples.

1. Modifying Existing Values in JSON

You can modify existing values in a JSON object.

Example:

#include "rapidjson/document.h"
#include "rapidjson/writer.h"
#include "rapidjson/stringbuffer.h"
#include <iostream>

int main() {
    const char* json = R"({"name":"John","age":30})";
    rapidjson::Document doc;
    doc.Parse(json);

    // Modify the value of "age"
    doc["age"] = 31;

    // Convert Document to JSON string
    rapidjson::StringBuffer buffer;
    rapidjson::Writer<rapidjson::StringBuffer> writer(buffer);
    doc.Accept(writer);

    std::cout << "Modified JSON: " << buffer.GetString() << std::endl;
    return 0;
}

2. Removing a Member from JSON

You can remove a member (key-value pair) from a JSON object.

Example:

#include "rapidjson/document.h"
#include "rapidjson/writer.h"
#include "rapidjson/stringbuffer.h"
#include <iostream>

int main() {
    const char* json = R"({"name":"John","age":30})";
    rapidjson::Document doc;
    doc.Parse(json);

    // Remove the "age" member
    doc.RemoveMember("age");

    // Convert Document to JSON string
    rapidjson::StringBuffer buffer;
    rapidjson::Writer<rapidjson::StringBuffer> writer(buffer);
    doc.Accept(writer);

    std::cout << "JSON after removal: " << buffer.GetString() << std::endl;
    return 0;
}

3. Checking for a Specific Key

You can check whether a specific key exists in the JSON.

Example:

#include "rapidjson/document.h"
#include <iostream>

int main() {
    const char* json = R"({"name":"John","age":30})";
    rapidjson::Document doc;
    doc.Parse(json);

    // Check if a key exists
    if (doc.HasMember("name")) {
        std::cout << "Key 'name' exists!" << std::endl;
    } else {
        std::cout << "Key 'name' does not exist!" << std::endl;
    }

    return 0;
}

4. Working with Arrays

You can create, modify, or iterate over arrays in JSON.

Example:

#include "rapidjson/document.h"
#include "rapidjson/writer.h"
#include "rapidjson/stringbuffer.h"
#include <iostream>

int main() {
    const char* json = R"({"fruits":["apple","banana","cherry"]})";
    rapidjson::Document doc;
    doc.Parse(json);

    // Access the array
    rapidjson::Value& fruits = doc["fruits"];
    for (rapidjson::SizeType i = 0; i < fruits.Size(); i++) {
        std::cout << "Fruit " << i << ": " << fruits[i].GetString() << std::endl;
    }

    // Add a new member to the array
    rapidjson::Value newFruit("orange", doc.GetAllocator());
    fruits.PushBack(newFruit, doc.GetAllocator());

    // Convert Document to JSON string
    rapidjson::StringBuffer buffer;
    rapidjson::Writer<rapidjson::StringBuffer> writer(buffer);
    doc.Accept(writer);

    std::cout << "Updated JSON: " << buffer.GetString() << std::endl;
    return 0;
}

5. Creating JSON from Scratch

You can create a JSON object from scratch.

Example:

#include "rapidjson/document.h"
#include "rapidjson/writer.h"
#include "rapidjson/stringbuffer.h"
#include <iostream>

int main() {
    rapidjson::Document doc;
    doc.SetObject();

    // Add values
    rapidjson::Value name("Alice");
    doc.AddMember("name", name, doc.GetAllocator());

    doc.AddMember("age", 25, doc.GetAllocator());

    // Create an array
    rapidjson::Value hobbies(rapidjson::kArrayType);
    hobbies.PushBack("reading", doc.GetAllocator());
    hobbies.PushBack("swimming", doc.GetAllocator());
    doc.AddMember("hobbies", hobbies, doc.GetAllocator());

    // Convert Document to JSON string
    rapidjson::StringBuffer buffer;
    rapidjson::Writer<rapidjson::StringBuffer> writer(buffer);
    doc.Accept(writer);

    std::cout << "Created JSON: " << buffer.GetString() << std::endl;
    return 0;
}

6. Converting JSON to String and Vice Versa

You can convert a JSON object to a string and vice versa.

Example:

#include "rapidjson/document.h"
#include "rapidjson/writer.h"
#include "rapidjson/stringbuffer.h"
#include <iostream>

int main() {
    // Convert JSON to string
    rapidjson::Document doc;
    doc.SetObject();
    doc.AddMember("name", "Bob", doc.GetAllocator());

    rapidjson::StringBuffer buffer;
    rapidjson::Writer<rapidjson::StringBuffer> writer(buffer);
    doc.Accept(writer);

    std::string jsonString = buffer.GetString();
    std::cout << "JSON String: " << jsonString << std::endl;

    // Convert string to JSON
    rapidjson::Document newDoc;
    newDoc.Parse(jsonString.c_str());

    if (newDoc.HasParseError()) {
        std::cerr << "Parse error!" << std::endl;
        return 1;
    }

    std::cout << "Name from parsed JSON: " << newDoc["name"].GetString() << std::endl;
    return 0;
}

7. Working with Different Data Types

RapidJSON supports various data types such as numbers, strings, booleans, and null.

Example:

#include "rapidjson/document.h"
#include "rapidjson/writer.h"
#include "rapidjson/stringbuffer.h"
#include <iostream>

int main() {
    rapidjson::Document doc;
    doc.SetObject();

    // Add different data types
    doc.AddMember("string", "Hello, World!", doc.GetAllocator());
    doc.AddMember("number", 42, doc.GetAllocator());
    doc.AddMember("boolean", true, doc.GetAllocator());
    doc.AddMember("null", rapidjson::Value(), doc.GetAllocator());

    // Convert Document to JSON string
    rapidjson::StringBuffer buffer;
    rapidjson::Writer<rapidjson::StringBuffer> writer(buffer);
    doc.Accept(writer);

    std::cout << "JSON with different data types: " << buffer.GetString() << std::endl;
    return 0;
}

8. Using Pointer for Accessing Values

RapidJSON supports Pointer (e.g., JSON Pointer) for accessing values within JSON.

Example:

#include "rapidjson/document.h"
#include "rapidjson/pointer.h"
#include <iostream>

int main() {
    const char* json = R"({"name":"John","address":{"city":"New York"}})";
    rapidjson::Document doc;
    doc.Parse(json);

    // Use Pointer to access a value
    rapidjson::Value* city = rapidjson::Pointer("/address/city").Get(doc);
    if (city) {
        std::cout << "City: " << city->GetString() << std::endl;
    } else {
        std::cerr << "City not found!" << std::endl;
    }

    return 0;
}

9. Using Schema for JSON Validation

RapidJSON supports Schema for validating the structure of JSON.

Example:

#include "rapidjson/document.h"
#include "rapidjson/schema.h"
#include "rapidjson/stringbuffer.h"
#include <iostream>

int main() {
    const char* json = R"({"name":"John","age":30})";
    const char* schemaJson = R"({"type":"object","properties":{"name":{"type":"string"},"age":{"type":"integer"}}})";

    rapidjson::Document doc;
    doc.Parse(json);

    rapidjson::Document schemaDoc;
    schemaDoc.Parse(schemaJson);

    rapidjson::SchemaDocument schema(schemaDoc);
    rapidjson::SchemaValidator validator(schema);

    if (!doc.Accept(validator)) {
        rapidjson::StringBuffer sb;
        validator.GetInvalidSchemaPointer().StringifyUriFragment(sb);
        std::cerr << "Invalid schema: " << sb.GetString() << std::endl;
    } else {
        std::cout << "JSON is valid!" << std::endl;
    }

    return 0;
}

10. Using PrettyWriter for Pretty Output

You can use PrettyWriter to generate nicely formatted JSON output.

Example:

#include "rapidjson/document.h"
#include "rapidjson/prettywriter.h"
#include "rapidjson/stringbuffer.h"
#include <iostream>

int main() {
    rapidjson::Document doc;
    doc.SetObject();
    doc.AddMember("name", "Alice", doc.GetAllocator());
    doc.AddMember("age", 25, doc.GetAllocator());

    // Use PrettyWriter
    rapidjson::StringBuffer buffer;
    rapidjson::PrettyWriter<rapidjson::StringBuffer> writer(buffer);
    doc.Accept(writer);

    std::cout << "Pretty JSON: " << buffer.GetString() << std::endl;
    return 0;
}

Conclusion

RapidJSON is a powerful and flexible library for working with JSON in C++. Using its methods and features, you can easily create, modify, parse, and validate JSON. It is suitable for both small and large projects and offers excellent performance.

What is a good API?

Amirmohammad Kazemi — Mon, 19 Feb 2024 11:19:33 +0000

API is the most powerful and useful concept in the computer world.

You can find API in the wide range of computer branches(such as web apps, operating systems, remote APIs). An application programming interface (API) is a way for two or more computer programs or components to communicate with each other. It is a type of software interface, offering a service to other pieces of software.

So API can help us to make and design better software and systems.

Be clear

Use logical and clear name for your API components: The names should be short and at the same time express the behavior of that components.

For example: example.com/prod/....

In this path, programmer want to show path of products, but is not clear. Is this prodded? or prodigality? or products?. So use clear syntax for resources, collections, and path names.

Good example1: example.com/products/123/....
Good example2: example.com/product/123/....

Good example 1 is good for products list. And good example 2 is good for using for one product.

Use clear comment for each piece of your code: Others should understand your code,or nor, you shouldn't understand your own code first?! Sometime you want to back to your codes and make some change or review it; comment help you for understanding what you did and every pieces of code has what behavior and how does it work.

Make response (error or success) messages useful

One of the most important part of each API is response per request.

The API response structure should be consistent and easy to understand. It should include a status code, a message, and the actual data being returned. The message should provide a brief explanation of the status code, and the data should be in a well-defined format, such as JSON, Protobuf, XML, GraphQL.

When creating a response object, it is wise only to return what the external user will need because building a large microservice will affect the performance and more.

When you're returning an error message when an external user queries the database, the message should be clear and concise – not just a generic error message like "Error Found" or "Error occurred."

This should be the title of the response, and the data or subject section should explain what sort of error occurred.

This is my personal take when creating an API error message. Do not return an unnecessary error message. Let's say some user data has a maximum character length of 5, and an external user queries the API for user data with a character length of 8.

Just message is not enough

Use message and error code

This method can make our API flexible. This codes can be use in other sides of system.

Don't Create Side Effects on the API

A side effect is, for example, when an external user queries an API for the user's first name but it returns the ID and full name.

When creating an API, try not to define everything in one function as much as possible. If the API sets many flags or does many tasks simultaneously, it should be split into multiple APIs. That's where atomicity comes to play.

Atomicity is when multiple operations are grouped into a single logical entity. Atomicity is important when creating an API. When using atomicity, poorly naming a function is just a terrible idea.

Stability

Consistency in APIs means no change in API behavior and performance over time. This is very important for developers because it gives them the confidence that their applications will work continuously and without problems.

There are several types of constants in APIs:

Behavioral stability:

This type of consistency ensures that the API always behaves the same way, regardless of what changes have occurred in the API's internal infrastructure.

For example, if a particular endpoint returns a JSON object with a certain structure, this structure should always remain constant.

Data consistency:

This type of consistency ensures that the data returned by the API is always accurate and consistent.

For example, if a particular endpoint returns information about a product, this information must always be up-to-date and correct.

Version stability:

This type of consistency ensures that different versions of the API are compatible with each other.
For example, if an API releases a new version, this version must work with applications that use previous versions of the API.

Principles of transactions

If you have worked with databases, you know that transactions must have certain characteristics in order to ensure their correctness.

It is better to refer to the database system design book to know these systems.

At The End

Designing a good API is like building a bridge.

A good bridge:

Makes it easy to cross, Is strong and reliable, Can handle a lot of traffic, Is secure

To build a good bridge:

You need to know the purpose of the bridge
You need to consider the needs of the people who will be using it
You need to design a clear path to follow
You need to use the right materials
You need to put up clear warning signs
You need to provide a complete and up-to-date map and guide
You need to test the bridge thoroughly
You need to protect your bridge from damage

By taking the time to design your API properly, you can create a valuable and efficient tool that will help you achieve your goals.

How to upload a video to GitHub?

Amirmohammad Kazemi — Fri, 21 May 2021 13:13:28 +0000

From: https://github.blog/2021-05-13-video-uploads-available-github/

Developers have always been interested in sharing bugs in the program or code in video. Because this method is much easier and more understandable.
That's why GitHub is trying to add this capability to its platforms.

When it comes to writing up a bug or describing a new feature, words only get you so far. Sometimes you need a video to easily illustrate the point.
That's why GitHub now gives you the ability to upload videos across its platform, in issues, pull requests, discussions, and more.
As developers, the ability to collaborate through video (for example, pair programming, demos, etc.) is an extremely important part of a software workflow, especially for communities and teams that are distributed. At GitHub, we’ve utilized video to more concisely detail complex workflows, show our teammates where we’re blocked, and inspire our colleagues with the next big idea.

Bugs are something that every developer deals with, but sometimes words aren’t enough to help someone else reproduce the problem quickly.

When it comes to developing a new feature or product, a thoughtfully worded proposal or static designs are great, but often lack the ability to really convey the end-to-end user workflows and interactions. Sharing videos of prototype walkthroughs or providing talk tracks for a static design have also helped development teams get to the heart of what they are setting out to build and why so they can get others excited about their work and ultimately build a better product for their own users.

No feature is truly complete until there is mobile support as well. So we’re also excited to announce that uploading videos from both the iOS and Android GitHub mobile apps is now available to all users. This is especially great for mobile developers who can now record a video of a mobile bug and upload it straight to an issue all from the same device.

It seems that GitHub will help developers a lot by developing this issue, and also if video uploading is added to GitHub, it will increase the level difference between this platform and the rest.