Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 20 additions & 20 deletions pages/spicedb/concepts/reflection-apis.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -3,24 +3,24 @@ import { InlinePlayground } from '@/components/playground';

# Reflection APIs

The [Experimental Reflection APIs] in SpiceDB (starting at version v1.33.0) provide the ability to reflect on the stored schema
The [Reflection APIs] in SpiceDB (starting at version v1.33.0) provide the ability to reflect on the stored schema
and type information to answer questions about the schema itself, as well as its permissions and
relations.

[Experimental Reflection APIs]: https://buf.build/authzed/api/docs/main:authzed.api.v1#authzed.api.v1.ExperimentalService
[Reflection APIs]: https://buf.build/authzed/api/docs/main:authzed.api.v1#authzed.api.v1.SchemaService.ReflectSchema

## ExperimentalReflectSchema
## ReflectSchema

`ExperimentalReflectSchema` provides an API-driven means of receiving the structure of the current
`ReflectSchema` provides an API-driven means of receiving the structure of the current
schema stored in SpiceDB.

It is designed primarily to allow callers to make dynamic decisions based on the structure of the
schema, such as being able to see all the permissions defined for a particular type of resource.

```proto
ExperimentalReflectSchemaRequest{}
ReflectSchemaRequest{}

ExperimentalReflectSchemaResponse{
ReflectSchemaResponse{
Definitions: []{
{ Name: "user" },
{
Expand All @@ -41,11 +41,11 @@ ExperimentalReflectSchemaResponse{

### Filtering

`ExperimentalReflectSchemaRequest` also includes support for filters which can be used to filter
`ReflectSchemaRequest` also includes support for filters which can be used to filter
the response to a specific subset of the schema:

```proto
ExperimentalReflectSchemaRequest{
ReflectSchemaRequest{
OptionalFilters: []{
{
OptionalDefinitionNameFilter: "a" // filter to defs starting with `a`
Expand All @@ -54,16 +54,16 @@ ExperimentalReflectSchemaRequest{
}
```

## ExperimentalDiffSchema
## DiffSchema

`ExperimentalDiffSchema` provides an API-driven means of comparing the currently stored schema
`DiffSchema` provides an API-driven means of comparing the currently stored schema
in SpiceDB to another schema.

This API is useful for tooling such as CI/CD that needs to determine what changes, if any,
exist between the current schema and a future schema.

```proto
ExperimentalDiffSchema{
DiffSchema{
ComparisonSchema: """
definition user {}

Expand All @@ -85,26 +85,26 @@ ExperimentalDiffSchema{
"""
}

ExperimentalReflectSchemaResponse{
ReflectSchemaResponse{
Diffs: []{
{ DefinitionDocCommentChanged: { Name: "organization", ... } },
{ PermissionExprChanged: { Name: "view", ... } },
}
}
```

## ExperimentalDependentRelations
## DependentRelations

`ExperimentalDependentRelations` is a reflection API that provides the list of relations and
`DependentRelations` is a reflection API that provides the list of relations and
permissions that are used to compute a particular permission.

```proto
ExperimentalDependentRelationsRequest{
DependentRelationsRequest{
DefinitionName: "resource"
PermissionName: "view"
}

ExperimentalDependentRelationsResponse{
DependentRelationsResponse{
Relations: []{
{ DefinitionName: "organization", RelationName: "member", IsPermission: false},
{ DefinitionName: "resource", RelationName: "org", IsPermission: false},
Expand All @@ -115,18 +115,18 @@ ExperimentalDependentRelationsResponse{
}
```

## ExperimentalComputablePermissions
## ComputablePermissions

`ExperimentalComputablePermissions` is the inverse of `ExperimentalDependentRelations`: it helps
`ComputablePermissions` is the inverse of `DependentRelations`: it helps
to determine any permissions impacted by a change to a relation or permission.

```proto
ExperimentalComputablePermissionsRequest{
ComputablePermissionsRequest{
DefinitionName: "resource"
RelationName: "viewer"
}

ExperimentalComputablePermissionsResponse{
ComputablePermissionsResponse{
Permissions: []{
{ DefinitionName: "resource", RelationName: "view", IsPermission: true},
}
Expand Down