Working with JSON documents

To get an understanding of how this works, consider the following JSON document saved in a file called demo.json (it can be any file), which contains an array of JSON objects with the name and priority key-value pairs:

[
 {
  "name": "Feature: Add support for X",
  "priority": 1
 },
 {
  "name": "Bug: Fix search performance",
  "priority": 2
 },
 {
  "name": "Feature: Create mobile page",
  "priority": 3
 }
]

Now, before looking at the API, it is important to understand how we need to perceive this JSON document. JSON defines only two data structures, one being an array that contains a list of values and the other an object that is just a name key-value pair. There are six value types in JSON, namely:

• String
• Number
• Object
• Array
• Boolean
• Null

In the previous document, the square brackets around the content denote an array that has multiple objects as its values. Let's take a look at the first JSON object, as follows:

{
 "name": "Feature: Add support for X",
 "priority": 1
}

The curly braces, {}, denote a JSON object that contains a key-value pair. The key must be a string in quotes followed by the value, which must be a valid JSON data type. In the previous case, we have the string in quotes, "Feature: Add support for X", and this maps to a String data type. The value of the "priority" key is a number data type, given as 1. Since the value can be any JSON data type, you could also have nested objects and arrays as values of the JSON object. Here's an example of that, showing the "ticket" key having an array as its value, which contains objects:

{ 
 "name": "Feature: Add support for X", 
 "priority": 1, 
 "ticket": [ 
   { 
    "name": "Feature: add new ticket", 
    "priority": 2 
   }, 
   { 
    "name": "Feature: update a ticket", 
    "priority": 2 
   } 
 ] 
}

Having built an understanding of this document structure, let's look at the API.