# Introduction

## Resources for JSON

* [What are JSON files and how do you use them?](https://blog.hubspot.com/website/json-files)
* [What is a JSON file?](https://docs.fileformat.com/web/json/)

## JSON File Basics

* JavaScript Object Notation
* Common format for communicating with Application Program Interface (API)
* Used to access DNAnexus API servers

## Why Should You Learn JSON?

* Reading and modifying JSON is at the heart of building and running apps
* Understanding JSON responses from the API will help you debug jobs
* Automation and Batch submissions: running the same app on multiple files
  * Find which jobs have failed and why
  * Run the failed jobs again

## Elements and Reading JSON

A valid JSON document is enclosed in one of two data structures, either a **list** of values contained in square brackets:

```
[
    {
        "project": "project-Gg2QQx002Q7yY4kFQF7GKYPV",
        "id": "applet-G1951vj0YyjJjbvGJ9FZB967",
        "describe": {
            "id": "applet-G1951vj0YyjJjbvGJ9FZB967",
            "project": "project-Gg2QQx002Q7yY4kFQF7GKYPV"
        }
    },
    {
        "project": "project-Gg2QQx002Q7yY4kFQF7GKYPV",
        "id": "file-GGy7Pbj0Xf47XZk125k22g9v",
        "describe": {
            "id": "file-GGy7Pbj0Xf47XZk125k22g9v",
            "project": "project-Gg2QQx002Q7yY4kFQF7GKYPV"
        }
    }
]
```

Or an **object** composed of key/value pairs contained in curly brackets:

Example:

```
{
   "report_html": {
       "dnanexus_link": "file-G4x7GX80VBzQy64k4jzgjqgY"
   },
   "stats_txt": {
       "dnanexus_link": "file-G4x7GXQ0VBzZxFxz4fqV120B"
   }
}
```

A JSON value may be any of the following:

* single- or double-quoted string, e.g., "samtools" or 'file-G4x7GX80VBzQy64k4jzgjqgY'
* integer, e.g. `19` or `-4`
* float, e.g., `3.14` or `6.67384e-11`
* boolean, e.g., `true` or `false`
* `null`
* object

## Lists

* Lists are braced in square brackets \[ ]
* Similar to Python syntax
* Used for multiple values separated by commas

Example:

```
{
    "dnanexus-link": [
        "file-G4x7GXQ0VBzZxFxz4fqV120B", "file-G4x7GX80VBzQy64k4jzgjqgY"
    ]
}
```

## Objects

* An object starts and ends with curly braces
* An object contains key/value pairs
* Keys must be quoted strings
* Values may be any JSON value, including another object

Example:

```
{ 
    "report_html": {
        "dnanexus_link": "file-G4x7GX80VBzQy64k4jzgjqgY"
    }
}
```

### Resources

[Full Documentation](https://documentation.dnanexus.com/)

To create a support ticket if there are technical issues:

1. Go to the Help header (same section where Projects and Tools are) inside the platform
2. Select "Contact Support"
3. Fill in the Subject and Message to submit a support ticket.