Design a tagging system and REST APIs
Company: Atlassian
Role: Software Engineer
Category: System Design
Difficulty: medium
Interview Round: Onsite
Design a tagging system (similar to tagging pages/issues) with a strong focus on REST API design.
Functional requirements:
- Create a tag.
- Rename a tag.
- Delete a tag.
- Attach/detach one or more tags to/from an entity (e.g., `page`, `issue`, etc.).
- List tags for an entity.
- Search entities by one or more tags (AND/OR semantics).
Non-functional requirements:
- Tags should be unique by name within a tenant/workspace.
- Handle concurrency and idempotency for attach/detach.
- Pagination for list/search endpoints.
Deliverables:
- Propose REST endpoints (request/response examples).
- Data model / DB schema.
- Indexing and query approach for tag search.
- Edge cases (deleting a tag that is attached, renaming collisions, bulk operations).
Overview: This question evaluates a candidate's ability in RESTful API design, data modeling, concurrency control, idempotency, pagination, and indexing/search strategies for a multi-tenant tagging system. It is commonly asked in the system design category to assess architectural decision-making and both conceptual understanding and practical application of endpoints, schema, and edge-case handling.
Read the full Atlassian Software Engineer interview experience this question came from
Community answers
Answer by freny07pethelis1996
name: Tagging Service
overview: "Atlassian system design: tags on issues and pages. Stable tag id, name unique per tenant, search by id, delete purges in the background."
todos:
id: api
content: REST for create, rename, delete, attach, detach, list, search
status: pending
id: model
content: tags, entity heads, reverse membership, outbox
status: pending
id: search
content: OpenSearch by tag id, cursor pagination, AND/OR
status: pending
id: edges
content: Rename collision, delete fanout, idempotent attach
status: pending
isProject: false
Tagging service — issues and pages
Atlassian onsite. Tags on entities the product already owns. Jira owns the issue. Confluence owns the page. This service owns the tag and the association. It does not own the issue body, and it does not run JQL.
Interactive board: Tagging service (repo). Cursor live board: tagging-service.canvas.tsx.
Thesis: A tag is an id. The name is a label on that id. The name is unique inside a tenant. Attachments and the search index store the id, so a rename updates one row and does not reindex every issue. Delete frees the name immediately and a worker removes the id from each entity in batches.
Say this: Rename is one row. Search filters on tag ids. Delete returns 202, the sidebar drops the tag on the next read, and the purge finishes in the background.
Clarifying questions → locked decisions
| Question | Locked for this design |
| --- | --- |
| What is an entity? | issue and page in v1. The id is the product's id (10