vscode-httpyac-config

VSCode httpYac Configuration

About This Skill

Transform API documentation into executable, testable .http files with httpYac. This skill provides workflow guidance for creating production-ready API collections with scripting, authentication, environment management, and CI/CD integration.

When to Use This Skill

• API Documentation → Executable Files: Converting API specs (Swagger, Postman, docs) to httpYac format
• Authentication Implementation: Setting up OAuth2, Bearer tokens, or complex auth flows
• Large Collections: Organizing 10+ endpoints with multi-file structure
• Request Chaining: Passing data between requests (login → use token → create → update)
• Environment Management: Dev/test/production environment switching
• Team Workflows: Git-based collaboration with secure credential handling
• CI/CD Integration: Automated testing in GitHub Actions, GitLab CI, etc.

Expected Outcomes

• ✅ Working .http files with correct httpYac syntax
• ✅ Environment-based configuration (.env files, .httpyac.json)
• ✅ Secure credential management (no secrets in git)
• ✅ Request chaining and response validation
• ✅ Team-ready structure with documentation
• ✅ CI/CD pipeline integration (optional)

---

Core Workflow

Phase 1: Discovery and Planning

Objective: Understand API structure and propose file organization.

Key Questions:

1. How many endpoints? (< 20 = single file, 20+ = multi-file)
2. Authentication method? (Bearer, OAuth2, API Key, Basic Auth)
3. Environments needed? (dev, test, staging, production)
4. Existing docs? (Swagger, Postman collection, documentation URL)

Propose Structure to User:

Identified API modules:
- Authentication (2 endpoints)
- Users (5 endpoints)
- Articles (3 endpoints)

Recommended: Multi-file structure
- auth.http
- users.http
- articles.http

Proceed with this structure?

📖 Detailed Guide: references/WORKFLOW_GUIDE.md

---

Phase 2: Template-Based File Creation

🚨 MANDATORY: Always start with templates from assets/ directory.

Template Usage Sequence:

1. Read assets/http-file.template
2. Copy structure to target file
3. Replace {{PLACEHOLDER}} variables
4. Add API-specific requests
5. Verify syntax against references/SYNTAX.md

Available Templates:

• assets/http-file.template → Complete .http file structure
• assets/httpyac-config.template → Configuration file
• assets/env.template → Environment variables

Key Files to Create:

• .http files → API requests
• .env → Environment variables (gitignored)
• .env.example → Template with placeholders (committed)
• .httpyac.json → Configuration (optional)

📖 File Structure Guide: references/WORKFLOW_GUIDE.md#phase-2

---

Phase 3: Implement Authentication

Select Pattern Based on API Type:

API Type	Pattern	Reference Location
Static token	Simple Bearer	references/AUTHENTICATION_PATTERNS.md#pattern-1
OAuth2 credentials	Auto-fetch token	references/AUTHENTICATION_PATTERNS.md#pattern-2
Token refresh	Auto-refresh	references/AUTHENTICATION_PATTERNS.md#pattern-3
API Key	Header or query	references/AUTHENTICATION_PATTERNS.md#pattern-5-6

Quick Example:

# @name login
POST {{baseUrl}}/auth/login
Content-Type: application/json

{
  "email": "{{user}}",
  "password": "{{password}}"
}

{{
  // Store token for subsequent requests
  if (response.statusCode === 200) {
    exports.accessToken = response.parsedBody.access_token;
    console.log('✓ Token obtained');
  }
}}

###

# Use token in protected request
GET {{baseUrl}}/api/data
Authorization: Bearer {{accessToken}}

📖 Complete Patterns: references/AUTHENTICATION_PATTERNS.md Search Pattern: grep -n "Pattern [0-9]:" references/AUTHENTICATION_PATTERNS.md

---

⚠️ CRITICAL SYNTAX RULES

🎯 Variable Management (Most Common Mistake)

1. Environment Variables (from .env file)

@baseUrl = {{API_BASE_URL}}
@token = {{API_TOKEN}}

✅ Use @variable = {{ENV_VAR}} syntax at file top

2. Utility Functions (in script blocks)

{{
  // ✅ CORRECT: Export with exports.
  exports.validateResponse = function(response, actionName) {
    return response.statusCode === 200;
  };
}}

###

GET {{baseUrl}}/api/test

{{
  // ✅ CORRECT: Call WITHOUT exports.
  if (validateResponse(response, 'Test')) {
    console.log('Success');
  }
}}

3. Response Data (post-response only)

GET {{baseUrl}}/users

{{
  // ✅ Store for next request
  exports.userId = response.parsedBody.id;
}}

❌ FORBIDDEN

{{
  // ❌ WRONG: Don't use exports/process.env for env vars
  exports.baseUrl = process.env.API_BASE_URL;  // NO!

  // ❌ WRONG: Don't use exports when calling
  if (exports.validateResponse(response)) { }  // NO!
}}

🔍 Post-Creation Checklist

• Template used as base
• ### delimiter between requests
• Variables: @variable = {{ENV_VAR}}
• Functions exported: exports.func = function() {}
• Functions called without exports
• .env.example created
• No secrets in .http files

📖 Complete Syntax: references/SYNTAX.md 📖 Common Mistakes: references/COMMON_MISTAKES.md 📖 Cheatsheet: references/SYNTAX_CHEATSHEET.md

---

Format Optimization for httpbook UI

Clean, Scannable Structure

# ============================================================
# Article Endpoints - API Name
# ============================================================
# V1-Basic | V2-Metadata | V3-Full Content⭐
# Docs: https://api.example.com/docs
# ============================================================

@baseUrl = {{API_BASE_URL}}

### Get Articles V3 ⭐

# @name getArticlesV3
# @description Full content + Base64 HTML | Requires auth | Auto-decode
GET {{baseUrl}}/articles?page=1
Authorization: Bearer {{accessToken}}

Format Guidelines

DO:

• ✅ Use 60-character separators: # =============
• ✅ Inline descriptions with |: Detail 1 | Detail 2
• ✅ @description for hover details
• ✅ Emoji for visual cues: ⭐⚠️📄

DON'T:

• ❌ 80+ character separators
• ❌ HTML comments <!-- --> (visible in UI)
• ❌ Multi-line documentation blocks
• ❌ Excessive ### decorations

📖 Complete Guide: See SKILL.md Phase 3.5 for before/after examples

---

Security Configuration

Essential .gitignore

# httpYac: Protect secrets
.env
.env.local
.env.*.local
.env.production

# httpYac: Ignore cache
.httpyac.cache
*.httpyac.cache
httpyac-output/

Security Rules

ALWAYS:

• ✅ Environment variables for secrets
• ✅ .env in .gitignore
• ✅ .env.example without real secrets
• ✅ Truncate tokens in logs: token.substring(0, 10) + '...'

NEVER:

• ❌ Hardcode credentials in .http files
• ❌ Commit .env files
• ❌ Log full tokens/secrets
• ❌ Disable SSL in production

📖 Complete Guide: references/SECURITY.md Search Pattern: grep -n "gitignore\|secrets" references/SECURITY.md

---

Reference Materials Loading Guide

Load references when:

Situation	File to Load	grep Search Pattern
Setting up authentication	references/AUTHENTICATION_PATTERNS.md	grep -n "Pattern [0-9]"
Script execution errors	references/SCRIPTING_TESTING.md	grep -n "Pre-Request|Post-Response"
Environment switching	references/ENVIRONMENT_MANAGEMENT.md	grep -n "\.env|\.httpyac"
Security configuration	references/SECURITY.md	grep -n "gitignore|secrets"
Team documentation	references/DOCUMENTATION.md	grep -n "README|CHANGELOG"
Advanced features	references/ADVANCED_FEATURES.md	grep -n "GraphQL|WebSocket|gRPC"
CI/CD integration	references/CLI_CICD.md	grep -n "GitHub Actions|GitLab"
Complete syntax reference	references/SYNTAX.md	grep -n "@|??|{{" references/SYNTAX.md

Quick References (Always Available):

• references/SYNTAX_CHEATSHEET.md - Common syntax patterns
• references/COMMON_MISTAKES.md - Error prevention
• references/WORKFLOW_GUIDE.md - Complete workflow

---

Complete Workflow Phases

This skill follows a 7-phase workflow. Phases 1-3 covered above. Remaining phases:

Phase 4: Scripting and Testing

• Pre/post-request scripts
• Test assertions
• Request chaining
• 📖 Reference: references/SCRIPTING_TESTING.md

Phase 5: Environment Management

• .env files for variables
• .httpyac.json for configuration
• Multi-environment setup
• 📖 Reference: references/ENVIRONMENT_MANAGEMENT.md

Phase 6: Documentation

• README.md creation
• In-file comments
• API reference
• 📖 Reference: references/DOCUMENTATION.md

Phase 7: CI/CD Integration (Optional)

• GitHub Actions setup
• GitLab CI configuration
• Docker integration
• 📖 Reference: references/CLI_CICD.md

---

Quality Checklist

Before completion, verify:

Structure:

• File structure appropriate for collection size
• Templates used as base
• Requests separated by ###

Syntax:

• Variables: @var = {{ENV_VAR}}
• Functions exported and called correctly
• No syntax errors (validated against references)

Security:

• .env in .gitignore
• .env.example has placeholders
• No hardcoded credentials

Functionality:

• All requests execute successfully
• Authentication flow works
• Request chaining passes data correctly

Documentation:

• README.md with quick start
• Environment variables documented
• Comments clear and concise

---

Common Issues

Symptom	Likely Cause	Solution
"Variable not defined"	Not declared with @	Add @var = {{ENV_VAR}} at top
"Function not defined"	Not exported	Use exports.func = function() {}
Scripts not executing	Wrong syntax/position	Verify {{ }} placement
Token not persisting	Using local variable	Use exports.token instead
Environment not loading	Wrong file location	Place .env in project root

📖 Complete Troubleshooting: references/TROUBLESHOOTING.md

---

Success Criteria

Collection is production-ready when:

1. ✅ All .http files execute without errors
2. ✅ Authentication flow works automatically
3. ✅ Environment switching tested (dev/production)
4. ✅ Secrets protected (.env gitignored)
5. ✅ Team member can clone and run in < 5 minutes
6. ✅ Requests include assertions
7. ✅ Documentation complete

---

Implementation Notes

Before Generating Files:

• Confirm structure with user
• Validate API docs completeness
• Verify authentication requirements

While Generating:

• Always use templates from assets/
• Validate syntax before writing
• Include authentication where needed
• Add assertions for critical endpoints

After Generation:

• Show created structure to user
• Test at least one request
• Highlight next steps (credentials, testing)
• Offer to add more endpoints

Common User Requests:

• "Add authentication" → Load references/AUTHENTICATION_PATTERNS.md → Choose pattern
• "Not working" → Check: variables defined, {{ }} syntax, .env loaded
• "Chain requests" → Use # @name and exports variables
• "Add tests" → Add {{ }} block with assertions
• "CI/CD setup" → Load references/CLI_CICD.md → Provide examples

---

Version

Version: 2.0.0 (Refactored) Last Updated: 2025-12-15 Based on: httpYac v6.x

Key Changes from v1.x:

• Refactored into modular references (7 files)
• Focused on workflow guidance and decision points
• Progressive disclosure design (load details as needed)
• grep patterns for quick reference navigation
• Reduced SKILL.md from 1289 to ~400 lines

Features:

• Template-based file generation
• 10 authentication patterns
• Multi-environment management
• Security best practices
• CI/CD integration examples
• Advanced features (GraphQL, WebSocket, gRPC)