diff --git a/pages/spicedb/concepts/reflection-apis.mdx b/pages/spicedb/concepts/reflection-apis.mdx index 4d73aa70..e97e46cc 100644 --- a/pages/spicedb/concepts/reflection-apis.mdx +++ b/pages/spicedb/concepts/reflection-apis.mdx @@ -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" }, { @@ -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` @@ -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 {} @@ -85,7 +85,7 @@ ExperimentalDiffSchema{ """ } -ExperimentalReflectSchemaResponse{ +ReflectSchemaResponse{ Diffs: []{ { DefinitionDocCommentChanged: { Name: "organization", ... } }, { PermissionExprChanged: { Name: "view", ... } }, @@ -93,18 +93,18 @@ ExperimentalReflectSchemaResponse{ } ``` -## 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}, @@ -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}, }