API Design: Resources

When designing APIs, resources represent data entities your API exposes, forming the core around which interactions are structured. An API resource represents a discrete unit of data within your system.

For example, in an e-commerce API, a product would be a resource. In a social media API, a user would be a resource.

Core Principles

  • Nouns, not Verbs: Resources are named using nouns, reflecting the entities they represent (e.g., /users, /products, /orders).
  • Structured Data: Each resource has a defined structure, often represented by a data schema (e.g., JSON, XML) with specific attributes and their data types.
  • Relationships with Other Resources: Resources can be linked to other resources, forming a rich data model (e.g., an order resource might have a relationship with a user resource and a product resource).
  • Collections and Individual Items: APIs often expose both collections of resources (e.g., /users) and individual resources within a collection (e.g., /users/123).

Rules to Follow

  • Resource names should be clear, concise, and consistent.
  • Keep in mind the granularity for resources.
  • Define resource relationships ahead of time.

API Endpoints and Resources

API endpoints, defined by URLs, map to specific resources and actions. Here’s how they interact:

  • Collections: Endpoints with a plural noun typically represent collections (e.g., /users).
    • The GET method is used to retrieve a list of all resources in the collection.
    • The POST method might be used to create a new resource within the collection.
  • Individual Items: Endpoints with a singular noun and an identifier typically represent individual resources (e.g., /users/123).
    • The GET method retrieves a specific resource based on its ID.
    • The PUT method updates an existing resource.
    • The DELETE method removes a resource.

Real-World Examples

Twitter API

  • Tweets: Core resource representing individual messages on the platform. A tweet resource might include:
    • Tweet text
    • Creation timestamp
    • Author information (User resource)
    • Like and retweet counts
  • Users: Resource representing Twitter accounts. Attributes might include:
    • Username
    • Display name
    • Profile bio
    • Follower/following count
  • Direct Messages: Resource for private conversations. Includes:
    • Message content
    • Sender/recipient information (User resources)

GitHub API

  • Repositories: Resources representing code projects. Might have:
    • Project name
    • Description
    • Programming language
    • Owner information (User resource)
    • Commit history (Commit resource)
  • Issues: Resources for bug tracking and feature requests. Includes:
    • Issue title
    • Description
    • Status (open, closed, etc.)
    • Labels (bug, feature-request, etc.)
  • Pull Requests: Resources for proposing and reviewing code changes. Attributes:
    • Title
    • Description
    • Code changes
    • Comments and Reviews

Stripe Payments API

  • Customers: Resources representing buyers on the platform. Includes:
    • Name
    • Email address
    • Associated payment methods (Payment Method resource)
  • Products: Resources representing goods or services available for purchase:
    • Product name
    • Description
    • Pricing/tiers (Price resource)
  • Orders: Resources representing transactions. Attributes:
    • Timestamp
    • Customer information (Customer resource)
    • Products purchased (often as line items)
    • Payment status