Overview

This document specifies the Resources gRPC service used to retrieve a single hypermedia Resource (Document, Comment, or Contact) by its IRI (URL). It complements the Documents and Comments APIs and avoids circular dependencies by concentrating read-only, cross-type lookup in a dedicated service.

Goals

Provide a simple, uniform lookup by IRI for key hypermedia entities (Document, Comment, Contact).

Allow clients to dereference a seed-hypermedia IRI/URL to a typed resource in one RPC.

Keep the service read-only and composable to avoid dependency cycles across subpackages.

Non‑Goals

Listing or searching resources (covered by other services).

Creating, updating, or deleting resources.

Expanding related entities (e.g., thread context, backlinks) beyond the direct payload.

Protocol Definition

syntax = "proto3";

package com.seed.documents.v3alpha;

import "documents/v3alpha/documents.proto";
import "documents/v3alpha/comments.proto";

option go_package = "seed/backend/genproto/documents/v3alpha;documents";

// Service for querying Hypermedia resources.
//
// Note: This API had to be separate to avoid circular dependencies between documents and comments.
service Resources {
  // Gets a single resource with a URL (technically IRI).
  rpc GetResource(GetResourceRequest) returns (Resource);
}

// Request to get a single resource by its IRI.
message GetResourceRequest {
  // Required. IRI of the resource to retrieve.
  string iri = 1;
}

// An identifiable entity, accessible with a unique identifier.
message Resource {
  // Various kinds of resources.
  oneof kind {
    Document document = 1;

    Comment comment = 2;

    Contact contact = 3;
  }

  // Optional. The version of the resource (when applicable).
  string version = 4;
}