TWMP YouTube Courses

API Data Formats

API Data Format

Establishing a common language is one of the key goals during communication and interaction. Sometimes, that language can be unique to the two persons involved, like a secret sign between friends. The most important thing is that the data format is in whatever way the intended audience can understand.

Data formats also apply to computers interacting via an API. Our middleman, aka API, which is somehow now tasked with translation, has to work with a format that the two computers will understand.

The most popular format is the JSON format (Javascript Object Notation) because it is both human-readable and machine-readable. However, there are many other formats, which we will explore in this chapter.

Types of API Data Format

JSON (Javascript Object Notation):

JSON is popular for several reasons. First, it is based on the popular Javascript language, making it compatible with front- and back-end web interactions. Second, it is human-readable. If you are familiar with the object syntax in Javascript, that is exactly how JSON is represented.

The JSON syntax consists of attribute-value pairs and arrays. An attribute-value pair is a key and its associated value, which can be a string, number, boolean, array, or another JSON object. On the other hand, arrays are ordered lists of values, which can be a mix of different data types.

Here is an example of a JSON syntax of our Petstore sample API

 1{
 2    "petId": 12345,
 3    "name": "Buddy",
 4    "species": "Dog",
 5    "breed": "Golden Retriever",
 6    "age": 5,
 7    "vaccinated": true,
 8    "owner": {
 9        "ownerId": 67890,
10        "firstName": "Jane",
11        "lastName": "Doe",
12        "contact": {
13            "email": "jane.doe@example.com",
14            "phone": "+123456789"
15        }
16    },
17    "appointments": [
18        {
19            "appointmentId": 1,
20            "date": "2024-08-20",
21            "time": "10:00 AM",
22            "service": "Vaccination"
23        },
24        {
25            "appointmentId": 2,
26            "date": "2024-09-15",
27            "time": "2:00 PM",
28            "service": "Grooming"
29        }
30    ]
31}

RESOURCES

JSON is a popular format and it would be important that you learn and understand its syntax and rules. We will not cover that in this course but there are detailed and beginner-friendly resources to learn and understand JSON.

We made a list of some of our favourites and hopefully, you will enjoy them too!

  1. JSON Course by W3 Schools: This is one of our favourites because it is beginner-friendly and has an interactive demo for you to practice.

  2. Video course on JSON: If you prefer videos, then this is for you.

  3. JSON course on Udemy: This course contains videos, classwork and quizzes that will guide you on mastering JSON and it’s absolutely FREE!

YAML (Yet Another Markup Language)

YAML was initially meant to be a markup language, which is why it was called Yet Another Markup language. However, YAML stands out from other markup languages like HTML and XML due to its unique feature: data serialization. This will slowly make sense when we see examples of an actual YAML syntax.

Like JSON, YAML has a simple and human-readable syntax. It can be called “JSON without the brackets.” The YAML syntax uses the Python indentation style to replace the brackets that exist in JSON. However, it retains the colon-center syntax between attributes-value pairs as we did in JSON.

Here is an example of a YAML syntax of our Petstore sample API:

 1    petId: 12345
 2    name: Buddy
 3    species: Dog
 4    breed: Golden Retriever
 5    age: 5
 6    vaccinated: true
 7    owner:
 8      ownerId: 67890
 9      firstName: Jane
10      lastName: Doe
11      contact:
12        email: jane.doe@example.com
13        phone: +123456789
14    appointments:
15      - appointmentId: 1
16        date: 2024-08-20
17        time: 10:00 AM
18        service: Vaccination
19      - appointmentId: 2
20        date: 2024-09-15
21        time: 2:00 PM
22        service: Grooming

RESOURCES

YAML is a very interesting format and you will learn to enjoy its simplicity. We will not cover the syntax in this course but there are detailed and beginner-friendly resources to learn and understand the format.

Here are some of them:

  • YAML Tutorial by TutorialsPoint: This course is free and beginner-friendly. It covers the basics of YAML syntax and usage.

  • ****A GitHub repo on YAML: This course will give you everything you need to get started and it includes a YAML Cheat code.

  • YAML Guide by Redocly: If you are looking for a quick and easy guide to YAML, then this course is perfect for you. It contains detailed examples of how to use YAML syntax.

XML (Extensible Markup Language)

XML stands for Extensible Markup Language. This format is widely used and interpreted by different systems. Its simple structure makes it both human-readable and machine-readable.

XML existed long before JSON and is known for formatting data using node building blocks. A node is an individual unit within the XML structure that represents a single piece of data.

Nodes can contain other nodes, creating a hierarchical structure that defines the relationships between different data elements. This allows XML to represent complex data models clearly and organized. Each node is enclosed in tags, with a start tag and an end tag, which define the boundaries of the data it contains.

Here is an example of an XML syntax of our Petstore sample API:

 1    <pet>
 2        <petId>12345</petId>
 3        <name>Buddy</name>
 4        <species>Dog</species>
 5        <breed>Golden Retriever</breed>
 6        <age>5</age>
 7        <vaccinated>true</vaccinated>
 8        <owner>
 9            <ownerId>67890</ownerId>
10            <firstName>Jane</firstName>
11            <lastName>Doe</lastName>
12            <contact>
13                <email>jane.doe@example.com</email>
14                <phone>+123456789</phone>
15            </contact>
16        </owner>
17        <appointments>
18            <appointment>
19                <appointmentId>1</appointmentId>
20                <date>2024-08-20</date>
21                <time>10:00 AM</time>
22                <service>Vaccination</service>
23            </appointment>
24            <appointment>
25                <appointmentId>2</appointmentId>
26                <date>2024-09-15</date>
27                <time>2:00 PM</time>
28                <service>Grooming</service>
29            </appointment>
30        </appointments>
31    </pet>

In this example, each piece of data, like petId, name, and species, is enclosed within its tags, making it a node. The pet node contains other nested nodes, such as owner and appointments, which further break down the data into more detailed information.

The tags in XML make the language bulky, hence the need for simpler and lightweight formats such as JSON and YAML.

RESOURCES

XML was quite popular and it is compatible with various systems. We will not cover its syntax in this course but there are detailed and beginner-friendly resources to learn and understand the format.

Here are some of them:

Raw

In RAW format, data is sent or received in an unprocessed or unencoded form through an API. This could be plain text, raw JSON, XML, or any other format that hasn’t been altered or transformed. When working with raw data formats, the data is typically sent directly over the network without additional encoding or compression. This approach is often used when the API needs to handle data in its original form or when the overhead of encoding or compression is unnecessary.

Here is an example of a Raw syntax of our Petstore sample API:

 1    
 2    POST /api/petstore HTTP/1.1
 3    Host: api.example.com
 4    Content-Type: application/json
 5    Content-Length: 123
 6    
 7    {
 8      "petId": 12345,
 9      "name": "Buddy",
10      "species": "Dog",
11      "breed": "Golden Retriever",
12      "age": 5,
13      "vaccinated": true
14    }
15

RESOURCES

RAW formats can come in handy, so understanding their syntax and structure can help you eliminate the need to use more complex formats like JSON and YAML.

We did not cover their syntax in this course, but we have picked out some of the best resources for you!

Here are some of them:

  • RAW Data Formats using NodeJs: In this course, you will learn how RAW data formats are used in APIs using an interactive demo.

Binary

In binary format, the data is encoded into binary—those familiar 0s and 1s. This format is typically machine-readable only. Binary API data formats offer significant advantages in terms of performance and speed. Since they are more compact and don’t require interpretation, they are ideal for transmitting large datasets, multimedia files, or complex data structures.

Here is an example of a Binary syntax of our Petstore sample API:

 1    syntax = "proto3";
 2    
 3    message Pet {
 4      int32 petId = 1;
 5      string name = 2;
 6      string species = 3;
 7      string breed = 4;
 8      int32 age = 5;
 9      bool vaccinated = 6;
10    }

RESOURCES

Binary format works best for operating system tasks and increased performance. While it is not human-friendly due to its format, it is a good option when working with large files.

We did not cover the syntax in this course but we have picked out some of the best resources for you!

Here are some of them:

Binary Data API: This explains the syntax and usage of Binary Data format.

Prev
WeatherStack API Documentation
Next
Structuring an API Document