Design a CRUD API for a document service
Company: Mintlify
Role: Backend Engineer
Category: Software Engineering Fundamentals
Difficulty: medium
Interview Round: Onsite
Design the CRUD API for a document service: clients create, read, update and delete documents. This came up as a fundamentals question in a short hiring-manager screen for a senior backend role, and the interviewer recorded the answer without asking follow-ups, so it has to be complete on its own: resources, endpoints, request and response shapes, status codes, and the behaviors a production API needs.
```hint Model the resource first
Decide what a document is in this API: which fields the server owns, which the client may set, and whether the content travels with the metadata.
```
```hint Two writers, one document
Two clients load the same document and both save changes. Decide how the API notices that the second save is based on stale data.
```
### Clarifying Questions
- What is a document: plain text or Markdown, structured rich text, or an uploaded file, and how large can it be?
- Who can access a document: only its owner, members of a workspace, or anyone with a link?
- Is version history required, and must deleted documents be recoverable?
- Do several people edit the same document at the same time?
- Who are the clients: the company's own web app, third-party integrations, or both?
### What a Strong Answer Covers
- A clear resource model separating server-owned fields from client-settable fields
- Endpoints for each operation with the right HTTP methods, status codes and a consistent error format
- Optimistic concurrency for updates, and idempotent creation under client retries
- Pagination, filtering and sorting for listing documents
- Authentication and authorization scoped to the document's owner or workspace
- Deletion semantics (soft delete, restore) and versioning of both documents and the API itself
### Follow-up Questions
- How would the API change to support real-time collaborative editing?
- How would you handle documents too large to send in one request?
- How would a client fetch only the documents that changed since its last sync?
- Which of these endpoints would you cache, and how would you invalidate the cache?
Overview: Design the create, read, update and delete API for a document service, covering the resource model, endpoints, request shapes and status codes. It tests REST fundamentals plus production concerns such as concurrent edits, idempotent retries, pagination, authorization, deletion semantics and API versioning.