Definition
Imagine you have a friend named Sarah. You could describe Sarah in many ways - a photograph, a written biography, a voice recording, a 3D avatar, or even a stick figure drawing. Sarah herself doesn’t change, but how you represent her depends on who’s asking and what they need. In APIs, a representation is exactly this - a specific format or snapshot of a resource at a particular moment in time.
When you request a resource from an API, you don’t get the resource itself (which is an abstract concept). You get a representation of it - the resource’s current state packaged in a format you can work with. The same user profile resource might be represented as JSON when your mobile app asks for it, as XML when an enterprise system needs it, as HTML when viewed in a browser, or as a PDF when you export it. The underlying data is the same; only the packaging changes.
This concept is the “R” in REST (Representational State Transfer). When you make an API call, state (data) is being transferred as a representation. The client and server negotiate which representation to use through content negotiation - you send an Accept: application/json header, and the server responds with JSON. This decouples the format from the data, making APIs incredibly flexible. A single endpoint can serve mobile apps, web browsers, legacy systems, and IoT devices - each receiving the representation they understand best.
Example
Multi-Platform Content Delivery: When you read a news article on CNN, the same article resource has multiple representations. Your mobile app receives a JSON representation with structured fields (headline, body, author, images array). The website renders an HTML representation with styling and navigation. Google’s crawler receives a stripped-down HTML representation optimized for indexing. RSS readers get an XML representation in Atom format. Apple News receives an Apple News Format JSON representation. Same article, five different representations.
API Response Formats: GitHub’s API demonstrates representations perfectly. When you request a repository (GET /repos/facebook/react), you can receive JSON (default for API clients), HTML (when viewed in browser), or even a tarball/zipball representation for downloading the code. Pull requests can be represented as JSON for API access, as unified diff format for code review tools, or as patch files for direct application.
Image Resources: Consider a profile photo resource. It exists as one logical resource but has many representations: the original high-resolution PNG, a compressed JPEG for web display, a small thumbnail for lists, a WebP version for modern browsers, an AVIF for cutting-edge compression, and even a base64-encoded string for inline embedding. Image CDNs like Cloudinary or Imgix dynamically generate representations based on query parameters - same image resource, hundreds of possible representations.
Financial Data: A stock quote resource can be represented differently based on needs. A real-time trading system might get a binary representation optimized for speed. A mobile app receives JSON with price, change, volume. A spreadsheet integration gets CSV format. A Bloomberg terminal receives a proprietary format. Historical analysis tools might get time-series JSON with hundreds of data points. Each consumer gets exactly the representation they need.
Document Resources: A document in Google Docs is a single resource with many representations. You can export it as PDF (for printing), as DOCX (for Word users), as ODT (for LibreOffice), as HTML (for web publishing), as plain text (for processing), or as EPUB (for e-readers). The document resource stays the same; representations are generated on demand.
Analogy
The Multilingual Tour Guide: Imagine a tour guide at the Louvre standing in front of the Mona Lisa. The painting (resource) is one thing, but the guide can represent it differently for each group - in French for locals, English for Americans, Mandarin for Chinese tourists, sign language for deaf visitors, or a Braille description for blind visitors. Same painting, same information, different representations tailored to each audience’s needs.
The Recipe in Different Formats: A recipe for chocolate cake is one resource, but it can be represented many ways. A printed cookbook shows it with beautiful photos and typography. A cooking website displays it with videos and step-by-step photos. A smart speaker reads it aloud step-by-step. A meal planning app shows it as structured data (ingredients list, nutrition info, prep time). A shopping app represents just the ingredients as a checklist. The recipe doesn’t change - only how it’s packaged for consumption.
The Musical Score: A symphony is one musical resource, but its representations vary wildly. The original handwritten score is one representation. A printed sheet music version is another. A MIDI file represents it digitally. An MP3 is an audio representation. A music visualization represents it visually. A conductor’s annotated score adds interpretation marks. Each musician’s part extracts just their instrument’s representation. Same symphony, countless representations.
The Blueprint vs. The Building: An architectural blueprint is a representation of a building design (the resource). The same design can be represented as 2D floor plans, 3D rendered images, VR walkthroughs, CAD files, material lists, construction schedules, or scale models. Contractors need detailed technical drawings; clients prefer photorealistic renders; city planners want site plans. Each representation serves a different purpose while describing the same building.
Code Example
// Same resource, different representations
GET /users/123
Accept: application/json
// Returns: {"id": 123, "name": "Alice"}
GET /users/123
Accept: application/xml
// Returns: <user><id>123</id><name>Alice</name></user>