11 min
URL Encoding: The Bug That Wasted My Entire Afternoon
I once spent 4 hours debugging an API call before realizing I'd used encodeURI instead of encodeURIComponent. Here's everything I learned so you don't make the same mistake.
Loading...
You've tested your API with cURL or copied a request from DevTools. Now you need to write actual code. Here's why manual translation is error-prone and how to automate it.
Here's a workflow I see constantly: developer opens DevTools, finds a network request, right-clicks, selects 'Copy as cURL'. They paste it into terminal to test. It works. Now they need to write the same request in their actual code.
And that's where things get tricky. cURL syntax is its own language. Translating `-H 'Content-Type: application/json'` to Python's requests library or JavaScript's fetch API requires knowing both syntaxes.
I've made this translation by hand hundreds of times. And I've made mistakes—forgotten headers, wrong method, malformed JSON body. Each mistake means another debug cycle. There has to be a better way.
cURL is everywhere. API documentation shows cURL examples. DevTools exports cURL. Postman exports cURL. When developers share API calls, they share cURL commands.
The reason is simple: cURL is universal and precise. It runs anywhere, captures every detail of an HTTP request, and doesn't require any specific language or framework knowledge to read.
But cURL is for testing and sharing, not for production code. At some point you need to translate that cURL command into actual application code. And that translation is where errors creep in.
The most common mistake I see is forgetting headers. cURL commands often have multiple `-H` flags, and it's easy to miss one when manually translating. Authentication headers are especially critical to get right.
Method confusion is another issue. cURL defaults to GET but automatically uses POST when you include data. Developers sometimes explicitly set the wrong method when translating.
JSON body handling trips people up too. cURL takes raw strings; most HTTP libraries want objects that they serialize. Getting the encoding right—especially with nested objects—requires attention.
Every language has its own HTTP client conventions. JavaScript has fetch (native) and axios (popular library). Python has requests. PHP has Guzzle. Go has net/http. Each has different syntax and idioms.
Knowing cURL doesn't automatically mean you know how to write the equivalent in every language. I primarily work in JavaScript, but when I need to write Python or Go code, I have to look up the syntax every time.
A cURL converter handles this translation automatically. You paste the cURL command, select your target language, and get idiomatic code for that language. No syntax lookup required.
Postman is great for API exploration. You can build requests visually, save them in collections, share with teammates. But at some point, you need to write actual code.
Postman has a built-in code generator, but I often find it generates verbose code or uses older patterns. Plus, you need Postman open. Sometimes you just have a cURL command someone shared in Slack.
My workflow now: test in Postman or DevTools, export as cURL if needed, convert to my target language, paste into my codebase. The whole process takes maybe 30 seconds.
Authentication headers are the most critical part of API requests. Missing or malformed auth means your request fails. cURL commands often include auth in several ways: `-u` for basic auth, `-H 'Authorization: Bearer ...'` for tokens, cookies, and more.
When converting, the tool needs to understand these different auth methods and translate them correctly. Basic auth `-u user:pass` becomes an Authorization header with base64 encoding. Bearer tokens stay as headers.
One thing I always do after conversion: double-check the auth code. If there's one place where errors are costly, it's authentication. A quick review ensures the token or credentials are being sent correctly.
Real-world API calls often involve more than simple GET or POST requests. File uploads, multipart forms, streaming responses, custom SSL certificates—cURL handles all of these with various flags.
A good converter handles these edge cases. File uploads with `@filename` syntax translate to multipart form data in your language. Insecure flags like `-k` become SSL verification settings. Timeout settings carry over.
For really complex cases, the converted code might need manual adjustment. But even then, starting with automatically converted code is faster than writing from scratch. The tool gets you 90% there; you finish the last 10%.
For modern projects, native fetch is usually fine—it's built in and widely supported. I use axios when I need request/response interceptors or automatic retry logic. Both work; fetch is simpler, axios has more features.
You could shell out to cURL, but you lose proper error handling, retries, timeouts, and integration with your application's patterns. Native HTTP clients integrate with your logging, monitoring, and error handling. cURL is for testing.
Never hardcode API keys from cURL commands. After conversion, replace inline keys with environment variables. The converted code is a starting point; you still need to follow security best practices.
GraphQL uses standard HTTP POST with a JSON body. cURL converters handle this fine—the body just happens to contain a GraphQL query. The converted code sends the same JSON payload to the GraphQL endpoint.
Some tools do this, though it's less common. It's useful when you want to share a request from your code with someone who uses a different language or wants to test in terminal. I mostly go cURL to code though.
The converter generates the request code, not response handling. You'll need to add response parsing, error handling, and retry logic yourself. That's the application-specific part that no tool can automate for you.
Founder of CodeUtil. Web developer building tools I actually use. When I'm not coding, I experiment with productivity techniques (with mixed success).
I once spent 4 hours debugging an API call before realizing I'd used encodeURI instead of encodeURIComponent. Here's everything I learned so you don't make the same mistake.
Learn how QR codes work internally, the different data types they support, error correction levels, size optimization, and how to generate them programmatically in various languages.
Master API debugging by learning to decode Base64 payloads and inspect JWT tokens. Troubleshoot authentication issues, read encoded error messages, and understand what your APIs are actually sending and receiving.