Reorganize the documentation and add some missing sections

docs/guides/first-app.mdx

@@ -18,11 +18,12 @@ Instead of introducing an unfamiliar example app and altering various locations
 
 One of:
 - An [Authzed] permission system and associated [API Token] with `admin` access
-- A running instance of [SpiceDB][SpiceDB] with the configured preshared key for SpiceDB
+- A [running instance] of [SpiceDB][SpiceDB] with the configured preshared key for SpiceDB
 
 [Authzed]: https://app.authzed.com
 [API Token]: /reference/api#authentication
 [SpiceDB]: https://github.com/authzed/spicedb
+[running instance]: /guides/getting-started-with-spicedb
 
 <SampleConfigEditor/>
 

docs/guides/installing.md

@@ -0,0 +1,60 @@
+# Installing SpiceDB
+
+:::info
+Want to use SpiceDB as a service without any installation? Visit the [Authzed Dashboard] to create a new permissions system
+:::
+
+[Authzed Dashboard]: https://app.authzed.com
+
+## Running SpiceDB in local mode
+
+To run [SpiceDB] for local testing, either Docker or brew can be used:
+
+[SpiceDB]: https://github.com/authzed/spicedb
+
+:::warning
+Running SpiceDB in this way is only to be used for local testing, as TLS is disabled and the data stored will disappear when SpiceDB is shut down.
+:::
+
+### Running via Docker
+
+```sh
+docker pull quay.io/authzed/spicedb
+```
+
+```sh
+docker run --name spicedb -d -p 50051:50051 quay.io/authzed/spicedb serve --grpc-preshared-key "somerandomkeyhere"
+```
+
+### Running via brew
+
+```sh
+brew install spicedb
+```
+
+```sh
+spicedb serve --grpc-preshared-key "somerandomkeyhere"
+```
+
+## Verifying that SpiceDB is running
+
+The [zed] tool can be used to check that SpiceDB is running, write schema and relationships, and perform other operations against SpiceDB:
+
+[zed]: https://github.com/authzed/zed
+
+### Running via brew
+
+```sh
+brew install zed
+```
+
+```sh
+zed context set local localhost:50051 "somerandomkeyhere" --insecure
+zed schema read --insecure
+```
+
+## Next Steps
+
+Continue with the [Protecting Your First App] guide to learn how to use SpiceDB to protect your application
+
+[Protecting Your First App]: /guides/first-app

docs/guides/rest-api.md

@@ -0,0 +1,29 @@
+# Using REST API
+
+:::note
+Want more information about the REST API and how to use it? Read our [blog post about the REST API]
+:::
+
+[blog post about the REST API]: https://authzed.com/blog/authzed-http-api/
+
+The standard means of calling the [SpiceDB API] is via **gRPC**.
+
+For environments where gRPC is not available, SpiceDB provides a REST gateway that exposes a REST API for making calls.
+
+[SpiceDB API]: https://buf.build/authzed/api/docs/main/authzed.api.v1
+
+## Running SpiceDB with the REST API
+
+To enable the REST API gateway on SpiceDB, add the flag `--http-enabled` to the SpiceDB arguments:
+
+```sh
+spicedb serve --grpc-preshared-key "secrettoken" --http-enabled
+```
+
+This will serve the REST API on port `8443` by default.
+
+## API Reference
+
+See the [REST API Reference].
+
+[REST API Reference]: /rest-api

docs/guides/schema.md

@@ -1,4 +1,4 @@
-# Developing a Schema
+# Developing Your Schema
 
 import {InlinePlayground} from '../../src/components/InlinePlayground';
 

docs/guides/writing-relationships.md

@@ -0,0 +1,88 @@
+# Writing Relationships
+
+:::note
+Want to learn more about writing relationships to SpiceDB, the various strategies and their pros and cons? Read our [blog post about writing relationships]
+:::
+
+[blog post about writing relationships]: https://authzed.com/blog/writing-relationships-to-spicedb/
+
+In [SpiceDB], a permissions system is defined by two items: the [schema] which defines *how* data can be represented, and the *relationships*, defining the way the objects are actually related to one another.
+
+[schema]: /guides/schema
+[SpiceDB]: https://github.com/authzed/spicedb
+
+It is the application's responsibility to keep the relationships within SpiceDB up-to-date and reflecting the state of the application; how an application does so can vary based on the specifics of the application, so below we outline a few approaches.
+
+## Two writes + commit
+
+The most common and straightforward way to store relationships in SpiceDB is to use a 2 phase commit-like approach, making use of a transaction from the relational database along with a [WriteRelationships] call to SpiceDB.
+
+[WriteRelationships]: https://buf.build/authzed/api/docs/main/authzed.api.v1#WriteRelationships
+
+```python title='Example of a 2PC-like approach'
+# Open the database transaction
+try:
+    with db.transaction() as transaction:
+        # Update the relationship in the database.
+        document = Document(
+            id="somedoc",
+            owner=some_user,
+        )
+        transaction.add(document)
+
+        # Add the relationship(s) in SpiceDB.
+        resp = client.WriteRelationships(...)
+
+        # Store the ZedToken we've received.
+        document.zedtoken = result.written_at
+
+        # Transaction is committed on close
+except:
+    # Delete the relationship(s) just written
+    client.DeleteRelationships(...)
+    raise
+```
+
+## Streaming commits
+
+Another approach is to stream updates to both a relational database and SpiceDB via a third party streaming system such as [Kafka], using a pattern known as [Command Query Responsibility Segregation] (CQRS)
+
+[Kafka]: https://kafka.apache.org/
+[Command Query Responsibility Segregation]: https://www.confluent.io/blog/event-sourcing-cqrs-stream-processing-apache-kafka-whats-connection/
+
+In this design, any updates to the relationships in both databases are published as **events** to the streaming service, with each event being consumed by a system which performs the updates in both the database and in SpiceDB.
+
+## SpiceDB-only relationships
+
+Sometimes, an application does not even need to store permissions-related relationships in its relational database.
+
+Consider a permissions system that allows for teams of users to be created and used to access a resource.
+In SpiceDB's schema, this could be represented as:
+
+```haskell
+definition user {}
+
+definition team {
+  relation member: user
+}
+
+definition resource {
+  relation reader: user | team#member
+  permission view = reader
+}
+```
+
+In the above example, the relationship between a resource and its teams, as well as a team and its members does not need to be stored in the application's database **at all**.
+
+Rather, this information can be stored solely in SpiceDB, and accessed by the application via a [ReadRelationships] or [ExpandPermissionsTree] call when necessary.
+
+[ReadRelationships]: https://buf.build/authzed/api/docs/main/authzed.api.v1#ReadRelationships
+[ExpandPermissionsTree]: https://buf.build/authzed/api/docs/main/authzed.api.v1#ExpandPermissionTree
+
+## Asynchronous Updates
+
+**NOTE:** This should *only* be used if your application supports less rigid consistency guarantees.
+
+If an application does not require up-to-the-second consistent permissions checking, and some replication lag in permissions checking is acceptable, then asynchronous updates of the relationships in SpiceDB can be used.
+
+In this design, a synchronization process, typically running in the background, is used to write relationships to SpiceDB in reaction to any changes that occur in the primary relational database.

docs/overview.md

@@ -16,23 +16,26 @@ Once stored, data can be performantly queried to answer questions such as "Does
 
 ## Getting Started
 
-- Log into the [Authzed dashboard] to create a serverless SpiceDB instance
-- Install and play with [SpiceDB] locally
+1. Log into the [Authzed dashboard] to create a serverless SpiceDB instance or [Install SpiceDB locally]
+2. Start the [Protecting Your First App] guide
+
+## Other Resources
+
 - Follow the guide for [developing a schema]
 - [Watch a video] of us modeling GitHub
 - Read the schema language [design documentation]
 - [Jump into the playground], load up some examples, and mess around
-- Learn the latest best practice by following the [Protecting Your First App] guide
 - Explore the gRPC API documentation on the [Buf Registry]
 - [Install zed] and interact with a live database
 
+[Install SpiceDB locally]: /guides/installing
 [Authzed]: https://authzed.com
 [Authzed dashboard]: https://app.authzed.com
 [SpiceDB]: https://github.com/authzed/spicedb
-[developing a schema]: https://docs.authzed.com/guides/schema
+[developing a schema]: /guides/schema
 [Watch a video]: https://www.youtube.com/watch?v=x3-B9-ICj0w
 [design documentation]: https://docs.authzed.com/reference/schema-lang
 [Jump into the playground]: https://play.authzed.com
-[Protecting Your First App]: https://docs.authzed.com/guides/first-app
+[Protecting Your First App]: /guides/first-app
 [Buf Registry]: https://buf.build/authzed/api/docs
 [Install zed]: https://github.com/authzed/zed

docusaurus.config.js

@@ -32,8 +32,8 @@ module.exports = {
       },
       items: [
         {
-          to: 'https://authzed.com',
-          label: 'Home',
+          to: '/',
+          label: 'Documentation',
           position: 'left',
         },
         {
@@ -43,11 +43,11 @@ module.exports = {
         },
         {
           to: 'https://app.authzed.com',
-          label: 'Dashboard',
+          label: 'Authzed Dashboard',
           position: 'left',
         },
         {
-          to: 'https://github.com/authzed',
+          to: 'https://github.com/authzed/spicedb',
           position: 'right',
           className: 'header-github-link',
         },
@@ -69,6 +69,7 @@ module.exports = {
       copyright: `© ${new Date().getFullYear()} Authzed. All rights reserved.`
     },
     algolia: {
+      appId: env('ALGOLIA_APP_ID', 'test'),
       apiKey: env('ALGOLIA_API_KEY', 'test'),
       indexName: env('ALGOLIA_INDEX', 'test'),
       contextualSearch: true,
@@ -119,5 +120,22 @@ module.exports = {
         pages: false,
       },
     ],
+    [
+      'redocusaurus',
+      {
+        // Plugin Options for loading OpenAPI files
+        specs: [
+          {
+            spec: 'https://raw.githubusercontent.com/authzed/authzed-go/main/proto/apidocs.swagger.json',
+            route: '/rest-api/',
+          },
+        ],
+        // Theme Options for modifying how redoc renders them
+        theme: {
+          // Change with your site colors
+          primaryColor: '#494B6C',
+        },
+      },
+    ],
   ],
 };

package.json

@@ -12,16 +12,17 @@
     "clear": "docusaurus clear"
   },
   "dependencies": {
-    "@docusaurus/core": "^2.0.0-beta.15",
-    "@docusaurus/module-type-aliases": "^2.0.0-beta.15",
-    "@docusaurus/plugin-client-redirects": "^2.0.0-beta.15",
-    "@docusaurus/preset-classic": "^2.0.0-beta.15",
+    "@docusaurus/core": "^2.0.0-beta.16",
+    "@docusaurus/module-type-aliases": "^2.0.0-beta.16",
+    "@docusaurus/plugin-client-redirects": "^2.0.0-beta.16",
+    "@docusaurus/preset-classic": "^2.0.0-beta.16",
     "@mdx-js/react": "^1.6.21",
     "amplitude-js": "^8.9.1",
     "clsx": "^1.1.1",
     "react": "^17.0.2",
     "react-cookie": "^4.1.1",
     "react-dom": "^17.0.2",
+    "redocusaurus": "^1.0.0",
     "string.prototype.replaceall": "^1.0.6",
     "twig": "^1.15.4"
   },
@@ -40,4 +41,4 @@
       "last 1 safari version"
     ]
   }
-}
+}

sidebars.js

@@ -2,37 +2,32 @@ module.exports = {
   someSidebar: [
     'overview',
     {
-      type: 'category',
-      label: 'Reference',
-      collapsed: false,
-      items: [
-        'reference/api',
-        'reference/clients',
-        {
-          type: 'link',
-          label: 'API Documentation',
-          href: 'https://buf.build/authzed/api/docs/main/authzed.api.v1',
-        },
-        'reference/api-consistency',
-        'reference/schema-lang',
-        'reference/zedtokens-and-zookies',
-        'reference/glossary',
-      ],
+      type: 'link',
+      label: 'gRPC API Reference',
+      href: 'https://buf.build/authzed/api/docs/main/authzed.api.v1',
+    },
+    {
+      type: 'link',
+      label: 'REST API Reference',
+      href: '/rest-api',
     },
     {
       type: 'category',
-      label: 'Guides',
+      label: 'Getting Started',
       collapsed: false,
       items: [
+        'guides/installing',
         'guides/first-app',
         'guides/schema',
         'guides/defining-a-subject-type',
+        'guides/writing-relationships',
+        'guides/rest-api',
       ],
     },
     {
       type: 'category',
       label: 'SpiceDB',
-      collapsed: false,
+      collapsed: true,
       items: [
         'spicedb/feature-overview',
         'spicedb/selecting-a-datastore',
@@ -41,11 +36,29 @@ module.exports = {
     {
       type: 'category',
       label: 'Authzed',
-      collapsed: false,
+      collapsed: true,
       items: [
         'authzed/pricing',
         'authzed/enterprise',
       ],
     },
+    {
+      type: 'category',
+      label: 'Reference',
+      collapsed: true,
+      items: [
+        'reference/api',
+        'reference/clients',
+        'reference/api-consistency',
+        'reference/schema-lang',
+        'reference/zedtokens-and-zookies',
+        'reference/glossary',
+        {
+          type: 'link',
+          label: 'API Reference',
+          href: 'https://buf.build/authzed/api/docs/main/authzed.api.v1',
+        },
+      ],
+    }
   ],
 };