recipe-schema-explore

Explore an API Before Using It

Discover and introspect any Google Workspace API using gws schema before executing commands.

When to Use

Use this workflow when the user wants to explore an unfamiliar API, check method parameters, or understand the request/response structure before making calls.

Steps

1. List available methods for a service:

   gws <service> --help
   

   Example:

   gws drive --help
   gws sheets --help
   

2. Drill into a resource:

   gws drive files --help
   gws sheets spreadsheets --help
   

3. Inspect method parameters:

   gws schema drive.files.list
   gws schema calendar.events.insert
   

4. Resolve nested type references:

   gws schema sheets.spreadsheets.create --resolve-refs
   

5. Inspect a specific type:

   gws schema gmail.Message
   gws schema drive.File
   

6. Test with a dry run:

   gws drive files list \
     --params '{"pageSize": 3}' \
     --fields "files(id,name)" \
     --dry-run
   

7. Execute with confidence:

   gws drive files list \
     --params '{"pageSize": 3}' \
     --fields "files(id,name)"
   

Tips

• Always start with gws schema when using an API for the first time
• Use --resolve-refs to see the full schema without chasing $ref pointers
• The schema data comes from Google's live Discovery Service — always current
• Combine --help (for CLI flags) with gws schema (for API structure)