Graph Service

The Graph Service manages the social graphs, including follow/unfollow actions, blocking users, and other social interactions. It allows applications to maintain and query the social connections between users on the Frequency network.

API Reference

Open Full API Reference Page

Path Table

Reference Table

Path Details

[POST]/v1/graphs/getGraphs

• Summary
  Fetch graphs for specified MSA Ids and Block Number

RequestBody

• application/json

{
  dsnpIds?: string[]
  // Graph type to query (public or private)
  privacyType: enum[private, public]
  graphKeyPairs: {
    // Public graph encryption key as a hex string (prefixed with "0x")
    publicKey: string
    // Private graph encryption key as a hex string (prefixed with "0x")
    privateKey: string
    // Key type of graph encryption keypair (currently only X25519 supported)
    keyType: enum[X25519]
  }[]
}

Responses

• 200 Graphs retrieved successfully

application/json

{
  // MSA Id that is the owner of the graph represented by the graph edges in this object
  dsnpId: string
  dsnpGraphEdges: {
    // MSA Id of the user represented by this graph edge
    userId: string
    // Block number when connection represented by this graph edge was created
    since: number
  }[]
}[]

[PUT]/v1/graphs

• Summary
  Request an update to a given user's graph

RequestBody

• application/json

{
  // MSA Id that owns the connections represented in this object
  dsnpId: string
  // Array of connections known to the Provider for ths MSA referenced in this object
  connections: #/components/schemas/ConnectionDtoWrapper
  graphKeyPairs: {
    // Public graph encryption key as a hex string (prefixed with "0x")
    publicKey: string
    // Private graph encryption key as a hex string (prefixed with "0x")
    privateKey: string
    // Key type of graph encryption keypair (currently only X25519 supported)
    keyType: enum[X25519]
  }[]
  // Optional URL of a webhook to invoke when the request is complete
  webhookUrl?: string
}

Responses

• 201 Graph update request created successfully

application/json

{
  // Reference ID by which the results/status of a submitted GraphChangeRequest may be retrieved
  referenceId: string
}

[GET]/v1/webhooks

• Summary
  Get all registered webhooks

Responses

• 200 Retrieved all registered webhooks

[PUT]/v1/webhooks

• Summary
  Watch graphs for specified dsnpIds and receive updates

RequestBody

• application/json

{
  dsnpIds?: string[]
  // Webhook URL to call when graph changes for the referenced MSAs are detected
  webhookEndpoint: string
}

Responses

• 200 Successfully started watching graphs

[DELETE]/v1/webhooks

• Summary
  Delete all registered webhooks

Responses

• 200 Removed all registered webhooks

[GET]/v1/webhooks/users/{msaId}

• Summary
  Get all registered webhooks for a specific MSA Id

Parameters(Query)

includeAll?: boolean

Responses

• 200 Retrieved all registered webhooks for the given MSA Id

[DELETE]/v1/webhooks/users/{msaId}

• Summary
  Delete all webhooks registered for a specific MSA

Responses

• 200 Removed all registered webhooks for the specified MSA

[GET]/v1/webhooks/urls

• Summary
  Get all webhooks registered to the specified URL

Parameters(Query)

url: string

Responses

• 200 Retrieved all webhooks registered to the specified URL

[DELETE]/v1/webhooks/urls

• Summary
  Delete all MSA webhooks registered with the given URL

Parameters(Query)

url: string

Responses

• 200 Removed all webhooks registered to the specified URL

[GET]/healthz

• Summary
  Check the health status of the service

Responses

• 200 Service is healthy

[GET]/livez

• Summary
  Check the live status of the service

Responses

• 200 Service is live

[GET]/readyz

• Summary
  Check the ready status of the service

Responses

• 200 Service is ready

References

#/components/schemas/GraphKeyPairDto

{
  // Public graph encryption key as a hex string (prefixed with "0x")
  publicKey: string
  // Private graph encryption key as a hex string (prefixed with "0x")
  privateKey: string
  // Key type of graph encryption keypair (currently only X25519 supported)
  keyType: enum[X25519]
}

#/components/schemas/GraphsQueryParamsDto

{
  dsnpIds?: string[]
  // Graph type to query (public or private)
  privacyType: enum[private, public]
  graphKeyPairs: {
    // Public graph encryption key as a hex string (prefixed with "0x")
    publicKey: string
    // Private graph encryption key as a hex string (prefixed with "0x")
    privateKey: string
    // Key type of graph encryption keypair (currently only X25519 supported)
    keyType: enum[X25519]
  }[]
}

#/components/schemas/DsnpGraphEdgeDto

{
  // MSA Id of the user represented by this graph edge
  userId: string
  // Block number when connection represented by this graph edge was created
  since: number
}

#/components/schemas/UserGraphDto

{
  // MSA Id that is the owner of the graph represented by the graph edges in this object
  dsnpId: string
  dsnpGraphEdges: {
    // MSA Id of the user represented by this graph edge
    userId: string
    // Block number when connection represented by this graph edge was created
    since: number
  }[]
}

#/components/schemas/ConnectionDto

{
  // MSA Id representing the target of this connection
  dsnpId: string
  // Indicator connection type (public or private)
  privacyType: enum[private, public]
  // Indicator of the direction of this connection
  direction: enum[connectionTo, connectionFrom, bidirectional, disconnect]
  // Indicator of the type of connection (follow or friendship)
  connectionType: enum[follow, friendship]
}

#/components/schemas/ConnectionDtoWrapper

{
  data: {
    // MSA Id representing the target of this connection
    dsnpId: string
    // Indicator connection type (public or private)
    privacyType: enum[private, public]
    // Indicator of the direction of this connection
    direction: enum[connectionTo, connectionFrom, bidirectional, disconnect]
    // Indicator of the type of connection (follow or friendship)
    connectionType: enum[follow, friendship]
  }[]
}

#/components/schemas/ProviderGraphDto

{
  // MSA Id that owns the connections represented in this object
  dsnpId: string
  // Array of connections known to the Provider for ths MSA referenced in this object
  connections: #/components/schemas/ConnectionDtoWrapper
  graphKeyPairs: {
    // Public graph encryption key as a hex string (prefixed with "0x")
    publicKey: string
    // Private graph encryption key as a hex string (prefixed with "0x")
    privateKey: string
    // Key type of graph encryption keypair (currently only X25519 supported)
    keyType: enum[X25519]
  }[]
  // Optional URL of a webhook to invoke when the request is complete
  webhookUrl?: string
}

#/components/schemas/GraphChangeRepsonseDto

{
  // Reference ID by which the results/status of a submitted GraphChangeRequest may be retrieved
  referenceId: string
}

#/components/schemas/WatchGraphsDto

{
  dsnpIds?: string[]
  // Webhook URL to call when graph changes for the referenced MSAs are detected
  webhookEndpoint: string
}

Configuration

ℹ️ Feel free to adjust your environment variables to taste. This application recognizes the following environment variables:

The following environment variables are only relevant if RECONNECTION_SERVICE_REQUESTED is 'true':

Best Practices

• Data Integrity: Ensure the integrity of social graph data by implementing robust validation checks.
• Efficient Queries: Optimize queries to handle large social graphs efficiently.
• User Privacy: Protect user privacy by ensuring that graph data is only accessible to authorized entities.