Katkat
Back

Design a CRUD API for a document service

MintlifyBackend Engineer · Onsite
MediumBackend EngineerOnsiteSoftware Engineering Fundamentals

Last updated

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.

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.

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?

Hints

Hint 1

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 2

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.

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?