# -*- restclient -*-
#
# REST API Tutorial — Free Public APIs
#
# QUICK START:
#   1. Place cursor on any request line (GET, POST, etc.)
#   2. C-c C-c   — execute request, results appear below
#   3. C-c C-p   — jump to previous request
#   4. C-c C-n   — jump to next request
#   5. TAB       — hide/show response body
#
# SYNTAX BASICS:
#   - Lines starting with # are comments
#   - Blank line separates comment/header blocks from the request
#   - :var = value defines a variable, use it as :var in requests
#   - Requests: METHOD URL, then headers, then body after blank line
#
# VARIABLES:
#   Define once, reuse everywhere. Variables persist across requests
#   in the same buffer.

:jsonplaceholder = https://jsonplaceholder.typicode.com
:httpbin = https://httpbin.org

#
# ============================================================
# JSONPlaceholder — fake REST API for testing
# ============================================================
#

# GET a single post
GET :jsonplaceholder/posts/1

#

# GET all posts by user 1
GET :jsonplaceholder/posts?userId=1

#

# POST a new post (returns 201 with fake ID)
POST :jsonplaceholder/posts
Content-Type: application/json

{
    "title": "Testing from Emacs",
    "body": "restclient.el is great for API exploration.",
    "userId": 1
}

#

# PUT (full update) — replaces post 1
PUT :jsonplaceholder/posts/1
Content-Type: application/json

{
    "id": 1,
    "title": "Updated Title",
    "body": "Updated body text.",
    "userId": 1
}

#

# PATCH (partial update) — only update the title
PATCH :jsonplaceholder/posts/1
Content-Type: application/json

{
    "title": "Just the title changed"
}

#

# DELETE a post
DELETE :jsonplaceholder/posts/1

#
# ============================================================
# httpbin — HTTP echo service
# ============================================================
#

# Echo back request headers (great for debugging auth)
GET :httpbin/headers

#

# Send custom headers and see them echoed back
GET :httpbin/headers
X-Custom-Header: hello-from-emacs
Accept: application/json

#

# Test Basic Auth (user: testuser, pass: testpass)
# httpbin checks credentials and returns 200 or 401
GET :httpbin/basic-auth/testuser/testpass
Authorization: Basic dGVzdHVzZXI6dGVzdHBhc3M=

#

# See your external IP
GET :httpbin/ip

#

# Test different status codes (change 418 to any HTTP status)
GET :httpbin/status/418

#

# POST with form data
POST :httpbin/post
Content-Type: application/x-www-form-urlencoded

name=Craig&tool=restclient

#
# ============================================================
# Tips & Tricks
# ============================================================
#
# JQ FILTERING (requires jq installed + restclient-jq):
#   Add -> jq-set-var :varname .path after a request to capture
#   a value from the JSON response into a restclient variable.
#
# MULTI-LINE BODIES:
#   Just write the JSON/XML body after a blank line. restclient
#   sends everything until the next # comment line.
#
# FILE ORGANIZATION:
#   Save related requests together in .rest files (e.g., per API
#   or per project). Open them with C-; R o.
#
# WORKFLOW:
#   1. Start with C-; R n (scratch buffer) for quick experiments
#   2. Save working requests to a .rest file for reuse
#   3. Use variables for base URLs and auth tokens