Yorkie

Web API

Yorkie Web API allows developers to interact programmatically with their Yorkie documents without using Yorkie SDK. It is convenient for managing documents in server-side applications.

The API is implemented using Connect protocol, which means all requests are made using HTTP POST method to a specific service endpoint. The API accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes.

Base URL: https://api.yorkie.dev/yorkie.v1.AdminService/

Authentication

For APIs that require authentication, you need to add your Project SecretKey to the request's authorization header.

curl 'https://api.yorkie.dev/yorkie.v1.AdminService/ListProjects' \
  -H 'content-type: application/json' \
  -H 'authorization: PROJECT_SECRET_KEY' \
  --data-raw '{}'

Documents Management

POST /yorkie.v1.AdminService/CreateDocument

This endpoint creates a new document in the specified project. If initial_root is provided, it will be used as the initial content of the document. Otherwise, an empty document will be created.

Request

Parameters:

  • project_name: The name of the project.
  • document_key: A unique key for the new document.
  • initial_root: The initial root(YSON string) of the document.
curl 'https://api.yorkie.dev/yorkie.v1.AdminService/CreateDocument' \
  -H 'content-type: application/json' \
  -H 'authorization: PROJECT_SECRET_KEY' \
  --data-raw '{
    "project_name": "my-project",
    "document_key": "document-1",
    "initial_root": "{\"type\":\"doc\",\"content\":[]}"
  }'

Response

{
  "document": {
    "id": "doc_abcdef",
    "key": "document-1",
    "project_name": "my-project",
    "snapshot": "{\"content\":[],\"type\":\"doc\"}",
    "created_at": "2025-05-12T10:00:00.000Z",
    "updated_at": "2025-05-12T10:00:00.000Z"
  }
}

POST /yorkie.v1.AdminService/UpdateDocument

This endpoint updates the content of an existing document.

Request

Parameters:

  • project_name: The name of the project.
  • document_key: The key of the document to update.
  • root: The new root content (YSON string) of the document.
curl 'https://api.yorkie.dev/yorkie.v1.AdminService/UpdateDocument' \
  -H 'content-type: application/json' \
  -H 'authorization: PROJECT_SECRET_KEY' \
  --data-raw '{
    "project_name": "my-project",
    "document_key": "document-1",
    "root": "{\"type\":\"doc\",\"content\":[{\"type\":\"paragraph\",\"content\":[{\"text\":\"Updated content\",\"type\":\"text\"}]}]}"
  }'
Response
{
  "document": {
    "id": "doc_12345",
    "key": "document-1",
    "project_name": "my-project",
    "snapshot": "{\"type\":\"doc\",\"content\":[{\"type\":\"paragraph\",\"content\":[{\"text\":\"Updated content\",\"type\":\"text\"}]}]}",
    "created_at": "2025-03-24T12:00:00.000Z",
    "updated_at": "2025-05-12T11:30:00.000Z"
  }
}

POST /yorkie.v1.AdminService/ListDocuments

This endpoint returns a list of documents in a project. There is a pagination mechanism to retrieve documents in batches. You can provide the previous_id of the last document in the previous page to get the next page of documents.

If you want to get the snapshot of the document, you can set the include_snapshot parameter to true.

Request

Parameters:

  • project_name: The name of the project.
  • previous_id: The ID of the last document in the previous page. If not provided, the first page will be returned.
  • page_size: The number of documents to return.
  • is_forward: Whether to return documents in ascending order.
  • include_snapshot: Whether to include snapshots in the response.
curl 'https://api.yorkie.dev/yorkie.v1.AdminService/ListDocuments' \
  -H 'content-type: application/json' \
  -H 'authorization: PROJECT_SECRET_KEY' \
  --data-raw '{
    "project_name": "my-project",
    "previous_id": "doc_last_id",
    "page_size": 20,
    "is_forward": true,
    "include_snapshot": false
  }'
Response
{
  "documents": [
    {
      "id": "doc_12345",
      "key": "document-1",
      "project_name": "my-project",
      "created_at": "2025-03-24T12:00:00.000Z",
      "updated_at": "2025-03-24T13:00:00.000Z",
      "snapshot": "..."
    },
    {
      "id": "doc_67890",
      "key": "document-2",
      "project_name": "my-project",
      "created_at": "2025-03-23T10:00:00.000Z",
      "updated_at": "2025-03-24T09:30:00.000Z",
      "snapshot": "..."
    }
  ]
}

POST /yorkie.v1.AdminService/GetDocument

This endpoint returns a document by its key.

Request

Parameters:

  • project_name: The name of the project.
  • document_key: The key of the document.
curl 'https://api.yorkie.dev/yorkie.v1.AdminService/GetDocument' \
  -H 'content-type: application/json' \
  -H 'authorization: PROJECT_SECRET_KEY' \
  --data-raw '{
    "project_name": "my-project",
    "document_key": "document-1"
  }'
Response
{
  "document": {
    "id": "doc_12345",
    "key": "document-1",
    "project_name": "my-project",
    "created_at": "2025-03-24T12:00:00.000Z",
    "updated_at": "2025-03-24T13:00:00.000Z"
  }
}

POST /yorkie.v1.AdminService/GetDocuments

Get multiple documents by their keys.

Request

Parameters:

  • project_name: The name of the project.
  • document_keys: An array of document keys.
  • include_snapshot: Whether to include snapshots in the response.
curl 'https://api.yorkie.dev/yorkie.v1.AdminService/GetDocuments' \
  -H 'content-type: application/json' \
  -H 'authorization: PROJECT_SECRET_KEY' \
  --data-raw '{
    "project_name": "my-project",
    "document_keys": ["document-1", "document-2"],
    "include_snapshot": false
  }'
Response
{
  "documents": [
    {
      "id": "doc_12345",
      "key": "document-1",
      "project_name": "my-project",
      "created_at": "2025-03-24T12:00:00.000Z",
      "updated_at": "2025-03-24T13:00:00.000Z"
    },
    {
      "id": "doc_67890",
      "key": "document-2",
      "project_name": "my-project",
      "created_at": "2025-03-23T10:00:00.000Z",
      "updated_at": "2025-03-24T09:30:00.000Z"
    }
  ]
}

POST /yorkie.v1.AdminService/RemoveDocumentByAdmin

Remove a document.

  • project_name: The name of the project.
  • document_key: The key of the document.
  • force: Whether to force remove the document event if they are attached to clients.
Request
curl 'https://api.yorkie.dev/yorkie.v1.AdminService/RemoveDocumentByAdmin' \
  -H 'content-type: application/json' \
  -H 'authorization: PROJECT_SECRET_KEY' \
  --data-raw '{
    "project_name": "my-project",
    "document_key": "document-1",
    "force": false
  }'
Response

Empty response with success status code.

POST /yorkie.v1.AdminService/GetSnapshotMeta

Get snapshot metadata for a document.

Request

Parameters:

  • project_name: The name of the project.
  • document_key: The key of the document.
  • server_seq: The server sequence number of the snapshot.
curl 'https://api.yorkie.dev/yorkie.v1.AdminService/GetSnapshotMeta' \
  -H 'content-type: application/json' \
  -H 'authorization: PROJECT_SECRET_KEY' \
  --data-raw '{
    "project_name": "my-project",
    "document_key": "document-1",
    "server_seq": 42
  }'
Response
{
  "snapshot": "base64-encoded-snapshot-data",
  "lamport": 42,
  "version_vector": {
    "client1": 5,
    "client2": 3
  }
}

POST /yorkie.v1.AdminService/SearchDocuments

Search for documents in a project.

Request

Parameters:

  • project_name: The name of the project.
  • query: The prefix of the document key to search for.
  • page_size: The number of documents to return.
curl 'https://api.yorkie.dev/yorkie.v1.AdminService/SearchDocuments' \
  -H 'content-type: application/json' \
  -H 'authorization: PROJECT_SECRET_KEY' \
  --data-raw '{
    "project_name": "my-project",
    "query": "search term",
    "page_size": 20
  }'
Response
{
  "total_count": 5,
  "documents": [
    {
      "id": "doc_12345",
      "key": "document-1",
      "project_name": "my-project",
      "created_at": "2025-03-24T12:00:00.000Z",
      "updated_at": "2025-03-24T13:00:00.000Z"
    },
    {
      "id": "doc_67890",
      "key": "document-2",
      "project_name": "my-project",
      "created_at": "2025-03-23T10:00:00.000Z",
      "updated_at": "2025-03-24T09:30:00.000Z"
    }
  ]
}

YSON

YSON(Yorkie Structured Object Notation) is a structured data format used by Yorkie to represent documents. It is similar to JSON but extends it with additional data types optimized for collaborative editing.

Data Types

YSON supports standard JSON types and adds specialized types for collaborative applications. Each YSON type has specific use cases and representation formats:

TypeDescriptionFormat ExampleUse Case
StringUTF-8 encoded text"value1"Text content
NumberStandard numeric value42.5Generic numeric values
BooleanTrue or falsetrueFlags and boolean states
NullNull valuenullAbsent or undefined values
ObjectCollection of key-value pairs{"key": "value"}Structured data
ArrayOrdered list of values[1, 2, 3]Sequential collections
Int32-bit integerInt(42)Precise integer values
Long64-bit integerLong(64)Large integer values
DateISO 8601 timestampDate("2025-01-02T15:04:05.058Z")Time values
BinDataBinary data with Base64 encodingBinData("AQID")Binary content
CounterConcurrent counterCounter(Int(10))Collaborative counting
TextList-based Rich TextText({"type":"p",...})List-based Rich Text Editor, e.g) Quill
TreeTree-based Rich TextTree({"type":"p",...})Tree-based Rich Text Editor

Custom Types Details

Int and Long

YSON provides explicit integer types to ensure consistent handling across platforms:

  • Int(number): A 32-bit integer type (-2,147,483,648 to 2,147,483,647)
  • Long(number): A 64-bit integer type for larger numbers

These types help ensure that numeric values are interpreted consistently when sharing documents across different programming languages.

Date

YSON Date represents a timestamp value in ISO 8601 format:

Date("2025-01-02T15:04:05.058Z")

Dates in YSON are stored as strings in ISO format for consistent representation across systems.

BinData

Binary data in YSON is represented using Base64 encoding:

BinData("AQID")  // Base64 encoded binary data

This allows binary content to be safely represented and transmitted as text.

Counter

Counter type is specifically designed for collaborative counting operations where multiple users might modify a numeric value concurrently:

Counter(Int(10))  // A counter with initial value of 10

Using Counter instead of a regular number prevents conflicts when multiple users increment or decrement values simultaneously.

Text

The Text type is designed for rich text editing, allowing for complex formatting and attributes:

Text([{"val":"Hello","attrs":{"color":"red"}},{"val":"World","attrs":{"color":"blue"}}])

This structure allows for a list of text segments, each with its own attributes, enabling rich text editing capabilities.

Tree

The Tree type provides a specialized structure for representing hierarchical data, particularly useful for rich text editing:

Tree({"type":"p","children":[{"type":"text","value":"Tree in object"}]})

This structure allows for a tree-based representation of rich text, where each node can have its own type and attributes.

Example Document

{
  "str": "value1",        // Standard string
  "num": 42,             // Standard number(float64)
  "int": Int(42),         // 32-bit integer
  "long": Long(64),        // 64-bit integer
  "null": null,            // Standard null
  "bool": true,            // Standard boolean
  "bytes": BinData("AQID"), // Binary data (Base64)
  "date": Date("2025-01-02T15:04:05.058Z"), // Date and time
  "counter": Counter(Int(10)), // Counter with integer value
  "text": Text([{"val":"Hello","attrs":{"color":"red"}},{"val":"World","attrs":{"color":"blue"}}]), // List-based Rich Text
  "tree": Tree({"type":"p","attrs":{"align":"center"},"children":[{"type":"text","value":"Hello World"}]}) // Tree-based Rich Text
}