API Documentation Languages

A Deep Dive into JSON and XML

Structured vs. Unstructured Data: What’s the Difference?

Structured data
  • Structured data is data that is organized in a predefined way, such as in a table or spreadsheet.

  • It is easy to search and analyze structured data because it has a clear and defined structure.

  • JSON and XML are both examples of structured data formats.

Unstructured data
  • Unstructured data is data that is not organized in a predefined way.

  • It can be text, images, audio, or video.

  • Unstructured data is more difficult to search and analyze than structured data because it does not have a clear and defined structure.

What are JSON and XML?

  • JSON and XML are both text-based data formats that can be used to store structured data.

  • JSON is a lightweight format that is easy to read and write.

  • XML is a more complex format that offers more flexibility.

Data types and structured data

  • Numbers: integer and decimal (floating) numbers

  • Text

  • True or False statements

  • Custom types

Data types in JOSN

  • JSON has three data types

Number, Strings, and Booleans

Data types in XML

  • XML has only one data types

    • Strings

Strings

  • Text group together inside single or double quotes ("string")

""
''

Strings

  • Text group together inside single or double quotes ("string")

"tribe"
'API documentation'
"2"

Strings

  • Text group together inside single or double quotes ("string")

  • Can have anything, from letter to numbers, to punctutation marks

  • Can have spaces

"tribe"
'API documentation'
"2"

Boolean

  • Boolean has only two values:

    • True

    • False

Vizualizing data types

data types

Collections

  • Structured data can have groups of data:

    • Arrays (lists)

    • Dictionaries (lookup tables)

Arrays

List of data values

  • It has:

    • A size

    • An order

Arrays

List of data values

  • It has:

    • A size

    • An order

list of numbers -> 5, 3, -7, 9

list of strings -> "tribe", "API documentation", "2"

Dictionary

Collection of data keys and values.

  • A key is used to look up a value, just like a dictionary

Dictionary

Collection of data keys and values.

  • A key is used to look up a value, just like a dictionary

A collection of Indian states with geo location.

"Uttar Pradesh": 10

Summary

Structured data can have:

  • Lists

  • Dictionaries

  • Dictionaries of lists

  • Lists of dictionaries

  • Dictionaries of dictionaries…​and so on

Why all this is important to know?

  • API rseponses almost always have structured data

  • API requests sometimes have strcutured data

request response

Tools to document JSON and XML

  • Text editors of your choice, like Visual Studio Code

JSON Basics

What is JSON?

JavaScript Object Notation (JSON) is a lightweight data-interchange format that is easy for humans to read and write and for machines to parse and generate.

Common Use Cases

JSON is widely used in web APIs for exchanging data, as developers can easily parse the data in almost any programming language.

Basic data types in JSON

  • Strings: text inside double or single quotation marks

  • Numbers: integer or floating, can be positive or negative

  • Booleans: true or false

  • Null: means nothing

Arrays

  • Enclosed in square brackets

[]

Arrays

  • Enclosed in square brackets

  • Comma-separated list

[4, 7, 0, -9, -10]

Arrays

  • Enclosed in square brackets

  • Comma-separated list

  • Can have combination of any data types

[4, 7, 0, -9, -10]
["blue", "red", "orange"]
["56, "book", true, "name", 40]

Objects

  • JSON’s dictionaries enclosed in curly bracket

{}

Objects

  • JSON’s dictionaries enclosed in curly bracket

  • Key value pair separated by commas

  • Keys and values are separated by a colon

  • Key and value can be of any data type

{"green": 46, "blue": 98, "pink": 45}

Objects

  • JSON’s dictionaries enclosed in curly bracket

  • Key value pair separated by commas

  • Keys and values are separated by a colon

  • Key and value can be of any data type

{"green": 46, "blue": 98, "pink": 45}
{
  "name": "John Doe",
  "age": 30,
  "city": "New York"
}

Nesting

Putting arrays and objects inside each other

  • Arrays inside objects

  • Objects inside arrays

  • Arrays inside Arrays

  • Objects inside objects

Real-world JSON examples:

Documenting JSON requests

Documenting JSON requests

Fields

field_name_1

Data type? Description? Example Value? Required? Constraints?

field_name_2

Data type? Description? Example Value? Required? Constraints?

field_name_n

Data type? Description? Example Value? Required? Constraints?

Documenting JSON requests

Field Name

Data Type

Description

Example Value

Required

Constraints

field_name_1

data_type_1

Description of the field.

"Example Value"

Yes/No

Constraints or limitations

field_name_2

data_type_2

Description of the field.

"Example Value"

Yes/No

Constraints or limitations

Example

{
 "name": "John Doe",
 "age": 30,
 "email": "johndoe@example.com",
 "subscribe": true
}

Note: All the data here is required. If not included, you may not get proper response from the server.

Documentation

Field Name

Data Type

Description

Example Value

Required

Constraints

name

string

The name of the user.

"John Doe"

Yes

Max length: 100 characters

age

number

The age of the user.

30

Yes

Must be a positive integer

email

string

The email address of the user.

"johndoe@example.com"

Yes

Valid email format

subscribe

boolean

Indicates whether the user wants to subscribe.

true

No

-

Documenting JSON responses

Field Name

Data Type

Description

Example Value

Constraints

Documenting JSON responses

Field Name

Data Type

Description

Example Value

Constraints

field_name_1

string

This field represents the name of the user.

"John Doe"

Max length: 50 characters

field_name_2

number

The user’s age.

30

Must be a positive integer

field_name_3

boolean

Indicates whether the user is active.

true

-

Example

{
  "user_id": 12345,
  "username": "johndoe",
  "email": "johndoe@example.com",
  "registered": true,
  "created_at": "2023-08-24T12:00:00Z"
}

Documentation

Field Name

Data Type

Description

Example Value

Constraints

user_id

number

The unique identifier of the user.

12345

Positive integer

username

string

The username of the user.

"johndoe"

Max length: 50 characters

email

string

The email address of the user.

"johndoe@example.com"

Valid email format

registered

boolean

Indicates whether the user is registered.

true

-

created_at

string

The timestamp when the user was created.

"2023-08-24T12:00:00Z"

ISO 8601 format

Documenting Nested JSON responses

  • Indentation - best when objects are not getting reused much

  • Separate Table - best when objects are geeting reused

Example → Indentation - best when objects are not getting reused much

Example → Indentation - best when objects are not getting reused much

{
  "user_id": 123,
  "tasks": [
    {
      "title": "Complete Project A",
      "status": "in_progress"
    }
  ]
}

Documentation

Field Name

Data Type

Description

Example Value

Documentation

Field NameData TypeDescriptionExample Value

user_id

number

The ID of the user

123

tasks

array

An array of tasks

    title

string

The title of the task

Complete Project A and Review Project B

   status

string

The status of the task

in_progress and pending

Example → Separate Table - best when objects are geeting reused

Example → Separate Table - best when objects are geeting reused

{
  "username": "johndoe",
  "email": "johndoe@example.com",
  "tasks": [
    {
      "task_id": 1,
      "status": "in_progress"
    },
    {
      "task_id": 2,
      "status": "pending"
    }
  ]
}

Documentation

Field Name

Data Type

Description

Example Value

Documentation

Field NameData TypeDescriptionExample Value

username

string

The username of the user.

"johndoe"

email

string

The email address of the user.

"johndoe@example.com"

tasks

array of objects

List of tasks associated with the user.

See task object details below

Task Object Structure

Field NameData TypeDescriptionExample Value

task_ID

string

The ID of the task.

"Complete Project A"

status

string

The status of the task.

"in_progress"

XML Basics

What is XML?

eXtensible Markup Language (XML) is a markup language for encoding documents in a format that is both human-readable and machine-readable.​

Historical Context​

XML was widely used in the past due to its ability to represent complex data structures and its compatibility with different systems.​

XML Syntax

XML has two ways of handling data:

  • Tags

  • Attributes

Tags

  • Start tag → <content>

  • End tag → </content>

  • Start and end tags should match.

  • You can only include letters, numbers, and underscores

Tags

  • Start tag → <content>

  • End tag → </content>

  • Start and end tags should match.

  • You can only include letters, numbers, and underscores

<name>John Doe</name>

Tags

  • Start tag → <content>

  • End tag → </content>

  • Start and end tags should match.

  • You can only include letters, numbers, and underscores

<name>John Doe</name>
  • The content in these tags called string

  • It can hold any data type

Tags

  • Start tag → <content>

  • End tag → </content>

  • Start and end tags should match.

  • You can only include letters, numbers, and underscores

<name>John Doe</name>
  • The content in these tags called string

  • It can hold any data type

<name>John Doe</name>
<age>25</age>
<isenabled>false</isenabled>

Nested tags

Placing tags inside tags

<library>
  <book>
    <title>Harry Potter and the Sorcerer's Stone</title>
    <author>J.K. Rowling</author>
    <genre>Fantasy</genre>
  </book>
  <book>
    <title>The Hobbit</title>
    <author>J.R.R. Tolkien</author>
    <genre>Fantasy</genre>
  </book>
</library>

Attributes

  • Key/value pair

  • Both are strings

  • Key have no quotes

  • Values have quotes

  • It can have letters, numbers, and underscores only

  • Must start with a letter

Attributes

  • Key/value pair

  • Both are strings

  • Key have no quotes

  • Values have quotes

  • It can have letters, numbers, and underscores only

  • Must start with a letter

<tag key="value">content</tag>

In APIs Attributes are used to indicate some property about data (also known as metadata) than data itself.

Attributes

<book isbn="978-0345391803"

Attributes

<book isbn="978-0345391803" category="Fantasy">
    <title>A Game of Thrones</title>
    <author>George R.R. Martin</author>
</book>

Attributes

<book isbn="978-0345391803" category="Fantasy">
    <title>A Game of Thrones</title>
    <author>George R.R. Martin</author>
    <pojectedCost decimals="3" confidence="5">32.45</projectedCost>
</book>

Documenting XML response

  • It is very similar to documeting JSON

  • An API request can have both of them

  • Elements in JSON are called tags in XML

XML has first line, we do not document it. It looks like → <?xml version="1.0" encoding="UTF-8"?>

<product>
  <name>Laptop</name>
  <price>999.99</price>
  <in_stock>true</in_stock>
</product>

Documentation

Field Name

Data Type

Description

Example Value

Documentation

Field Name

Data Type

Description

Example Value

product

-

The root element that represents a product’s information.

-

    name

String

The element containing the name of the product.

Content: Laptop

   price

Number

The element containing the price of the product.

Content: 999.99

  in_stock

Boolean

The element indicating whether the product is in stock.

Content: true

Attributes inside tags

<product category="electronics">
  <name

Attributes inside tags

<product category="electronics">
  <name brand="Apple">iPhone 12</name>
  <price

Attributes inside tags

<product category="electronics">
  <name brand="Apple">iPhone 12</name>
  <price currency="USD">899.99</price>
  <in_stock available="true"/>
</product>

Documentation

Element

Data Type

Attributes

Description

Example Value

Element

Data Type

Attributes

Description

Example Value

product

-

-

The root element representing a product.

-

   name

String

brand: String

The name of the product.

Content: iPhone 12, Attribute: brand="Apple"

   price

Number

currency: String

The price of the product.

Content: 899.99, Attribute: currency="USD"

   in_stock

Boolean

available: Boolean

Indicates if the product is in stock.

Attribute: available="true"

Documenting XML request

<createUserRequest>
  <username>johndoe</username>
  <age>28</age>
  <is_active>true</is_active>
</createUserRequest>

Documentation

ElementData TypeRequiredDescriptionExample Value

createUserRequest

-

Yes

The root element for creating a new user.

-

   username

String

Yes

The username of the new user.

Content: johndoe

   age

Integer

Yes

The age of the new user.

Content: 28

   is_active

Boolean

No

Indicates whether the new user is active.

Content: true

JSON vs XML

user-journey

Thank you for your time and attention!

question