Definition
Think about everything you interact with on the internet - your Facebook profile, a YouTube video, a product on Amazon, a tweet, your bank account balance. Each of these is a “resource” in API terms. A resource is simply anything that can be named, identified, and manipulated through an API. It’s the fundamental building block of how we think about and organize data on the web.
The concept comes from REST architecture, where everything is modeled as resources with unique addresses (URIs). The key insight is that resources are nouns, not verbs. You don’t have an API endpoint called “getUser” or “deleteOrder” - instead, you have resources called “users” and “orders” that you perform operations on. This might seem like a subtle distinction, but it completely changes how APIs are designed and makes them much more intuitive.
Resources can be individual items (a specific user with ID 123) or collections (all users). They can be nested (all orders belonging to user 123) or related (the reviews for product 456). The same resource can have different representations - JSON for your mobile app, XML for a legacy system, HTML for a browser. What makes something a resource is that it has identity, state, and a uniform interface for interaction.
Example
Social Media Platform: On Twitter/X, resources are everywhere. Your profile (/users/johndoe) is a resource. Each tweet (/tweets/1234567890) is a resource. Your followers (/users/johndoe/followers) are a collection resource. When you like a tweet, you’re creating a new resource (/tweets/1234567890/likes). The timeline you see (/users/johndoe/timeline) is also a resource - a dynamically generated collection of tweets. Even abstract concepts like trending topics (/trends) are modeled as resources.
E-commerce System: Amazon’s API likely has dozens of resource types. Products (/products/B08N5WRWNW), product reviews (/products/B08N5WRWNW/reviews), shopping carts (/carts/current), orders (/orders/111-2222222-3333333), wish lists (/wishlists/abc123), and delivery tracking (/shipments/TBA123456789). Each resource has its own lifecycle - a cart becomes an order, an order spawns shipments, shipments update their status over time.
Banking API: Your bank account (/accounts/1234567890) is a resource with a current balance. Transactions (/accounts/1234567890/transactions) are a collection resource that grows over time. Each transaction (/transactions/TXN123) is itself a resource with details like amount, merchant, and timestamp. Transfers (/transfers/TRF456) are resources that represent money movement between accounts. Even scheduled payments (/scheduled-payments/SP789) are resources that can be created, modified, or cancelled.
Content Management System: In WordPress or similar systems, posts (/posts/hello-world), pages (/pages/about), media files (/media/image-123.jpg), categories (/categories/technology), tags (/tags/api), and comments (/posts/hello-world/comments) are all resources. Users (/users/admin), roles (/roles/editor), and even settings (/settings/site-title) are resources too.
IoT Platform: In a smart home system, each device is a resource - your thermostat (/devices/thermostat-living-room), lights (/devices/light-bedroom-1), door locks (/devices/lock-front-door). Their current states are resources (/devices/thermostat-living-room/state). Automation rules (/automations/night-mode) are resources. Even scheduled events (/schedules/morning-routine) and activity logs (/devices/lock-front-door/history) are resources.
Analogy
The Filing Cabinet System: Imagine a massive, perfectly organized filing cabinet. Each drawer is labeled (like /customers or /invoices). Inside each drawer are folders (individual resources like /customers/acme-corp). Some folders contain sub-folders (/customers/acme-corp/contracts). Every single item has a unique label that tells you exactly where to find it. When you need something, you don’t say “get me the thing from that place” - you say “get me /customers/acme-corp/contracts/2024-service-agreement”. That’s exactly how resources work in APIs.
The Library System: A library is a perfect resource metaphor. Books (/books/978-0-13-468599-1), DVDs (/media/dvd-12345), magazines (/periodicals/time-2024-01), and even library members (/members/M123456) are all resources. Each has a unique identifier (ISBN, call number, member ID). You can check the status of any resource, borrow it, return it, or request it. The library catalog is itself a collection resource. The waiting list for a popular book is a resource. The analogy extends perfectly to nested resources - a book’s reviews, a member’s checkout history, a branch’s available copies.
The Real Estate Model: Think of resources like properties in real estate. Each property (/properties/123-main-street) has a unique address. Properties have attributes (bedrooms, square footage, price) that can change over time. They belong to collections (/properties?city=boston). They have related resources - photos (/properties/123-main-street/photos), inspection reports (/properties/123-main-street/inspections), price history (/properties/123-main-street/price-history). Actions on properties (listing, selling, renting) change their state but the property resource remains the same entity.
The Museum Collection: A museum’s collection demonstrates resources beautifully. Each artwork (/artworks/mona-lisa) is a resource with attributes (artist, year, medium, dimensions). The artist (/artists/leonardo-da-vinci) is a related resource. Exhibitions (/exhibitions/renaissance-masters) are collection resources that group artworks. Audio guides (/artworks/mona-lisa/audio-guide) are nested resources. Even the museum’s floor plan (/museum/floor-plan) and visiting hours (/museum/hours) are resources that can be queried.
Code Example
// Resources in a REST API
GET /products // Collection resource
GET /products/456 // Individual resource
GET /products/456/reviews // Nested resource
POST /products // Create new resource
PUT /products/456 // Update resource
DELETE /products/456 // Delete resource