Essential Formats & Data

Speak the language — understand the data formats and structures you'll encounter constantly in development.

INFO

• Time: ~45 minutes
• Difficulty: Beginner
• What you'll learn: Markdown, JSON, environment variables, REST APIs

---

This Page Covers

• Markdown: the universal documentation format
• JSON: structured data format
• Environment variables and secrets
• REST APIs and how to read documentation

---

Markdown

Why It's Everywhere

Markdown is the universal language for writing formatted text in development. You will encounter it constantly:

• GitHub READMEs — every project has one explaining what it does
• Documentation — technical docs, wikis, and knowledge bases
• Notes apps — Notion, Obsidian, and many note-taking tools use Markdown
• This course — these pages are written in Markdown

The beauty of Markdown is that it is plain text that looks readable even without rendering, but transforms into nicely formatted content when displayed.

Basic Syntax

Here is the essential Markdown syntax you need to know:

# Heading 1
## Heading 2
### Heading 3

**bold** and *italic*

- Bullet list
- Another item
  - Nested item

1. Numbered list
2. Second item

[Link text](https://url.com)
![Image alt text](image.png)

`inline code`

```javascript
// code block
const x = 1;

Blockquote for callouts

Column 1	Column 2
Cell 1	Cell 2

Quick reference:

• Use # for headings (more # = smaller heading)
• Wrap text in ** for bold, * for italic
• Start lines with - or * for bullet lists
• Start lines with numbers for numbered lists
• Use backticks for code (single for inline, triple for blocks)

Where You'll Use It

README files: Every project needs a README.md explaining:

• What the project does
• How to install and run it
• How to contribute

Project documentation: Write guides, tutorials, and reference docs in Markdown. Most documentation tools (GitBook, Docusaurus, MkDocs) use Markdown as their source format.

Notes and planning: Keep project notes, meeting summaries, and technical decisions in Markdown files right in your repository.

---

JSON

Structure and Syntax

JSON (JavaScript Object Notation) is a structured data format used everywhere in web development. Think of it like a form with labeled fields — each piece of data has a name and a value.

{
  "name": "John",
  "age": 30,
  "isStudent": false,
  "skills": ["JavaScript", "Python", "SQL"],
  "address": {
    "city": "Amsterdam",
    "country": "Netherlands"
  }
}

Key concepts:

• Objects use curly braces {} and contain key-value pairs
• Arrays use square brackets [] and contain lists of values
• Keys are always strings in double quotes
• Values can be strings, numbers, booleans (true/false), arrays, objects, or null

Common Use Cases

JSON appears in many places:

• Configuration files — package.json, tsconfig.json, VS Code settings
• API responses — when you fetch data from a server, it usually comes back as JSON
• Data storage — many databases and files use JSON format

Reading and Writing JSON

Reading nested structures: Work from the outside in. In the example above:

• address is an object inside the main object
• To get the city: address.city would give you "Amsterdam"
• skills[0] would give you "JavaScript" (arrays start at 0)

Rules to remember:

• Keys must be in double quotes (not single quotes)
• Strings must be in double quotes (not single quotes)
• No trailing commas after the last item
• No comments allowed in JSON files

Common mistakes:

{
  "name": "John",
  "age": 30,    // ERROR: trailing comma!
}

{
  'name': 'John'  // ERROR: single quotes not allowed!
}

{
  "name": "John"
  "age": 30      // ERROR: missing comma between items!
}

---

Environment Variables

What They Are

Environment variables are settings stored outside your code. Think of them as secret notes that your application can read but that are not visible in your codebase.

They solve several problems:

• Keep secrets safe — API keys, passwords, and tokens should never be in your code
• Different environments — use different database URLs for development vs production
• Easy configuration — change settings without modifying code

.env Files

A .env file stores environment variables in a simple format:

API_KEY=sk-abc123xyz
DATABASE_URL=postgres://user:pass@host/db
DEBUG=true
SITE_NAME=My Awesome App

Format rules:

• One variable per line
• Format is NAME=value
• No spaces around the =
• No quotes needed (unless value contains spaces)
• Lines starting with # are comments

The .env.example pattern: Include a .env.example file in your repository showing what variables are needed, but with fake values:

# Copy this to .env and fill in real values
API_KEY=your-api-key-here
DATABASE_URL=postgres://localhost/mydb
DEBUG=false

Security Considerations

Critical rule: Never commit .env files to Git!

Add .env to your .gitignore file immediately:

# .gitignore
.env
.env.local
.env.*.local

What happens if you leak secrets:

• Your API keys get exposed publicly
• Malicious actors can use your keys (costing you money)
• You need to regenerate all exposed credentials immediately
• If it is a database password, your data could be compromised

Even if you delete a file from Git, the history keeps it forever. If you accidentally commit secrets, you need to rotate (change) those credentials immediately.

---

REST APIs

What APIs Are

An API (Application Programming Interface) is a way for programs to talk to each other. When you use an app that shows weather data, that app is calling a weather API to get the information.

Think of it like ordering at a restaurant:

• You (the client) make a request to the server
• The kitchen (the API) processes your order
• You get back a response with your food (data)

HTTP Methods (GET, POST, etc.)

HTTP methods are like verbs that describe what action you want to take:

Method	Action	Example
GET	Read/fetch data	"Give me the list of users"
POST	Create new data	"Add this new user"
PUT	Replace existing data	"Replace this user's info entirely"
PATCH	Update part of existing data	"Change this user's email only"
DELETE	Remove data	"Delete this user"

Most of the time you will use GET (to read data) and POST (to send data).

Request and Response Structure

A request contains:

• URL — where to send the request (e.g., https://api.example.com/users)
• Method — what action to take (GET, POST, etc.)
• Headers — metadata like authentication tokens
• Body — data you are sending (for POST, PUT, PATCH)

A response contains:

• Status code — was it successful? (200 = OK, 404 = Not Found, 500 = Server Error)
• Headers — metadata about the response
• Body — the actual data, usually in JSON format

Common status codes:

• 200 — Success
• 201 — Created successfully
• 400 — Bad request (you sent something wrong)
• 401 — Unauthorized (need to log in)
• 403 — Forbidden (logged in but not allowed)
• 404 — Not found
• 500 — Server error (something broke on their end)

---

Reading API Documentation

Finding What You Need

API documentation typically includes these sections:

• Base URL — the root address (e.g., https://api.example.com)
• Endpoints — paths you can call (e.g., /users, /products/123)
• Parameters — data you can send (query params, path params, body)
• Authentication — how to prove who you are
• Examples — sample requests and responses

When reading API docs, look for:

1. The base URL first
2. The endpoint you need
3. What authentication is required
4. Example requests showing the format

Authentication Sections

Most APIs require authentication to identify who is making requests:

API Keys: A secret string you include in your requests.

Authorization: Bearer sk-abc123xyz

OAuth: A more complex flow where users authorize your app to access their data. Common with Google, GitHub, etc.

Headers: Authentication info usually goes in request headers:

GET /users HTTP/1.1
Host: api.example.com
Authorization: Bearer your-api-key-here
Content-Type: application/json

Example Requests

Documentation often shows curl examples (curl is a command-line tool for making HTTP requests):

curl -X GET "https://api.example.com/users" \
  -H "Authorization: Bearer sk-abc123xyz" \
  -H "Content-Type: application/json"

Breaking this down:

• -X GET — the HTTP method
• The URL in quotes — where to send the request
• -H — headers to include
• \ at end of line — continues on next line

When you see curl examples, you are looking for:

• The URL and endpoint
• Required headers (especially Authorization)
• Any data being sent in the body

---

Key Takeaways

• Markdown is the standard for documentation and README files
• JSON structures data with objects, arrays, and key-value pairs
• Environment variables keep secrets out of code
• APIs use HTTP methods (GET, POST, etc.) to transfer data
• API docs show endpoints, authentication, and examples