API Data Encoding Guide: JSON, Base64, URL and More

The Encoding Problem in API Development

APIs fail silently when data encoding is wrong. A misencoded URL parameter returns a 400. A missing Content-Type header causes the server to misparse your JSON body. A Base64 string pasted into a URL without re-encoding causes a 500. These errors are frustrating because the data is correct—only the packaging is wrong.

This guide maps out the correct encoding for every common API data type.

JSON Body Encoding

For REST API POST and PUT requests with a JSON body:

• Set Content-Type: application/json
• Serialize your data structure to a valid JSON string
• Validate the structure with JSON Formatter before sending
• Common pitfall: sending a JavaScript object without JSON.stringify() produces [object Object]

URL Query Parameter Encoding

For GET requests with query parameters:

• Each key and value must be percent-encoded separately
• Use the URL Encoder to encode values containing special characters
• Never encode the entire URL as one string—only encode parameter values
• Common pitfall: including unencoded ampersands in values splits the parameter prematurely

For a deep dive, see our Advanced URL Encoding Guide.

Base64 for Binary Data

When an API accepts binary data (images, PDFs, audio) inside a JSON payload:

• Encode the binary file as Base64 using the Base64 Encoder
• Pass the Base64 string as a JSON string value
• Set Content-Type to application/json (not multipart/form-data)
• Common pitfall: using standard Base64 (with + and /) in a URL parameter—use URL-safe Base64 or re-encode with the URL Encoder

Multipart Form Data

For file uploads via HTTP forms or APIs expecting multipart/form-data:

• The boundary string separates each field
• Text fields use UTF-8 encoding
• Binary files are sent as raw bytes (no Base64)
• Common pitfall: setting Content-Type manually and overriding the browser's auto-generated boundary

Authentication Headers

HTTP Basic Auth: Base64-encode the string username:password and send as Authorization: Basic {encoded}. Note this is not secure without HTTPS—the Base64 is trivially reversible with Base64 Decoder.

Bearer tokens (JWT): Tokens are already Base64-encoded. Pass them as Authorization: Bearer {token} without additional encoding.

Webhook Payload Signing

Many webhooks use HMAC-SHA256 signatures. The server signs the raw request body with a secret key and sends the hex-encoded signature in a header. Your validation must hash the exact raw body bytes—not a re-serialized version.

Explore the Developer Tools hub and Encoding Tools hub for all the utilities needed to debug and verify API encoding issues.

Conclusion

Correct API encoding is a protocol contract. Match the server's expected Content-Type, encode parameters individually, use Base64 for binary data in JSON, and verify signatures against raw bytes. When in doubt, use the formatting and encoding tools in this guide to inspect every step.

Need a faster workflow? Try the AI Resume Summary — Generate an impactful, professional summary for your resume using AI-driven analysis. Pivot your career or highlight your key strengths in seconds.

Need a faster workflow? Try the JPG to PNG — Convert your JPG images to high-quality PNG format instantly. Ideal for web designers and developers who need lossless compression and transparency.

Need a faster workflow? Try the Text Case Converter — Quickly transform your text between different capitalization styles. Supporting Title Case, Sentence case, camelCase, snake_case, and more.

Need a faster workflow? Try the Lorem Ipsum Generator — Generate high-quality placeholder text for your web designs, brochures, and layouts. Customizable by paragraph, sentence, and word count.