Requirements of the File API

Discover how to design a file storage API by learning its key functional operations like upload, download, delete, and list. Understand crucial non-functional requirements such as reliability, security, scalability, and low latency. This lesson helps you evaluate API architecture choices and plan for efficient communication between clients and backend services.

We'll cover the following...

Introduction
- File service
Requirements
- Functional requirements
- Non-functional requirements
Prerequisites
How will we design a file API?

Introduction

File or cloud storage services are gaining popularity because they offer cheaper, more reliable storage without the worry of manually managing and upgrading space. We can upload various media, such as photos, videos, documents, and software, to the cloud storage service. The media can be downloaded later when needed. Cloud storage services are designed to be reliable, so users can access their data as is when needed. The most popular cloud storage services today include Google Drive, Microsoft OneDrive, Amazon Drive, Dropbox, and MediaFire.

Let's now see what a file service looks like at an abstract level.

File service

Cloud storage services work by transferring files from one computer system (client) to another (host), which is usually a more powerful computer system with a large storage capacity. From a client's perspective, uploading a file to remote storage may look like a simple API call, as shown below:

In reality, uploading files is a complex system of multiple services working together, some on the frontend and some on the backend. In this chapter, we will design an API service for storing files, learn about its main components, and discuss how these components affect our design decisions.

Requirements

Before actually designing an API, we must first clearly define the desired functionality, security constraints, resiliency, performance expectations, and cost goals from a usage perspective. Below are some requirements for our hypothetical file API.

Functional requirements

Upload: The API should allow users to securely upload files to remote storage.
Download: The API should allow users to download the uploaded files from remote storage.
Delete: The API should allow only the file owners to delete uploaded files from remote storage.
List: The API should allow file owners to list uploaded files in remote storage.

Non-functional requirements

Reliability: Data should not be lost or corrupted during the transfer (during upload and download operations). Additionally, data must be stored persistently after a successful upload.
Security: The API should adopt appropriate security mechanisms to provide secure access to data.
Scalability: The API should be scalable to handle the increasing number of users and files.
Availability: The API should have high availability, allowing users to upload/download data on demand.
Low latency: The API should be able to upload/download data with low latency.

You’re designing a file storage API with operations like upload, download, delete, and list. The system has two communication stages:

Client to API gateway: The client authenticates and interacts via standard HTTP operations (e.g., uploading/downloading files).
API gateway to internal services: The gateway coordinates metadata extraction, database updates, file processing, and blob storage with multiple downstream services.

Which communication style (REST, gRPC, or GraphQL) would you choose for each stage, and why? Use the AI assessment widget below to submit your solution and get an interactive response.