gron Session 02: API Discovery

Real APIs return deeply nested JSON you’ve never seen before. gron lets you explore the structure without reading docs first.

Pre-Session State

  • Can flatten JSON with gron

  • Can grep paths and ungron results

  • Have gh CLI authenticated

Lesson 1: Explore Your GitHub Profile

Exercise 1.1: Flatten your user profile

gh api user | gron | head -30

Every field in the response, as a flat list. No need to read API docs first.

Exercise 1.2: Find specific info

gh api user | gron | grep -i repo
gh api user | gron | grep -i created
gh api user | gron | grep -i bio

Exercise 1.3: Discover, then extract with jq

# gron discovered: json.public_repos, json.created_at, json.login
gh api user | jq '{login, repos: .public_repos, created: .created_at}'

Lesson 2: Explore Repository Data

Exercise 2.1: Repository fields

gh api 'repos/EvanusModestus/domus-captures' | gron | head -40

Exercise 2.2: Find language and size info

gh api 'repos/EvanusModestus/domus-captures' | gron | grep -iE 'lang|size|topic'

Exercise 2.3: Explore permissions

gh api 'repos/EvanusModestus/domus-captures' | gron | grep permissions

Now extract with jq:

gh api 'repos/EvanusModestus/domus-captures' | jq '.permissions'

Lesson 3: Explore Commits

Exercise 3.1: Flatten commit data

gh api 'repos/EvanusModestus/domus-captures/commits?per_page=3' | gron | head -50

Exercise 3.2: Find commit messages

gh api 'repos/EvanusModestus/domus-captures/commits?per_page=5' | gron | grep message

Now you see the path: json[0].commit.message. Use it in jq:

gh api 'repos/EvanusModestus/domus-captures/commits?per_page=5' | jq '.[].commit.message'

Exercise 3.3: Find author info

gh api 'repos/EvanusModestus/domus-captures/commits?per_page=3' | gron | grep author

Notice: there’s .commit.author (git author) and .author (GitHub user). gron reveals both.

Lesson 4: Search API Exploration

Exercise 4.1: Explore code search structure

gh search code "vault seal" --owner EvanusModestus --json repository,path,textMatches --limit 3 | gron | head -30

Exercise 4.2: Find the right field names

gh search code "vault seal" --owner EvanusModestus --json repository,path --limit 3 | gron | grep -i name

This reveals json[0].repository.full_name — now you know it’s full_name, not fullName.

Lesson 5: Reconstruct Filtered Views

Exercise 5.1: Extract just repo metadata

gh api 'repos/EvanusModestus/domus-captures' | gron | grep -E '(name|description|language|topics)' | gron --ungron

Valid JSON containing only the matched fields.

Exercise 5.2: Compare two endpoints

# What fields does /user have that /repos/:owner/:repo doesn't?
diff <(gh api user | gron | awk -F'.' '{print $2}' | sort -u) \
     <(gh api 'repos/EvanusModestus/domus-captures' | gron | awk -F'.' '{print $2}' | sort -u)

Process substitution (<(…​)) + diff — compare structure across endpoints.

Exercises to Complete

  1. [ ] Explore gh api 'repos/EvanusModestus/domus-nvim' — find the default branch name

  2. [ ] Use gron to discover the path to stargazers count, then extract with jq

  3. [ ] Flatten the branches API (gh api 'repos/EvanusModestus/domus-captures/branches'), find protection info

  4. [ ] Compare field names between two different repos

Next Session

Session 03: Composition - gron + jq + yq multi-tool pipelines.

Session Log

Timestamp Notes

Start

<Record when you started>

End

<Record when you finished>