Search⌘ K
AI Features
Home
Courses
Grokking the Product Architecture Interview

API Model for File Service

Explore how to design a REST-based file service API that supports uploading, downloading, listing, and deleting files. Understand key data entities, request and response formats, HTTP methods, and security considerations. Learn to incorporate best practices for handling file metadata, binary content, user authorization, and error responses in a scalable and reliable architecture.

We'll cover the following...

Now we know the workflow of the file API and the architecture that best suits our needs. The next step is to identify the data entities involved in the API calls to meet the functional requirements and map those API calls to the chosen architecture (REST).

Base URL and API endpoints

The base URL is the common/shared path of all endpoints of the API service. Below is a structural breakdown of the base URL of our file service:

Base URL breakdown of the file API
Base URL breakdown of the file API

Basic operations

The figure below shows a summary of the operations and the HTTP verbs used with the various endpoints defined by the file API.

Message format for API endpoints

Let's discuss the data entities and the request-response format involved in our API calls.

File API data entities

Our API will make use of the following data entities while performing different functions.

YAML
type file
{
    fileId: string      // Unique identifier of a file on the host system
    ownerId: string     // Unique identifier of a user on the host system
    authToken: string   // Token verifying the authenticity and privileges of the user
    checksum: string    // Hash value verifying the integrity of data
    fileLink: string    // The URI of the stored the file contents
    userList: list      // A list of users with the specified permissions to access the resource
    timeStamp: date     // The data and time at which the particular file is uploaded
    fileTitle: string   // The name/title of the file along with its extension
    fileSize: long      // Total size of a file in bytes
    content: binary     // The actual content of a file being transferred
    mimeType: *         // file format or extension of the file such as png, jpeg, mp3, mkv, etc.
}

Preconditions

Before discussing the file API model, we assume the following:

  • Our server is configured to handle file size limits and other similar checks.

  • The user is logged in.

  • We provide a flat directory structure for the user to manage files.

Upload a file

Users can upload a file specifying the relevant HTTP method and ...