API CSS

docs/fides/docs/api/index.md

@@ -1,9 +1,35 @@
-# API Reference
+# Fides Control API
 
-You can view the live, interactive [Swagger](https://swagger.io/docs/) API docs for Fidesctl by visiting `/docs` on a running instance. This is a great way to experiment with the APIs using Swagger's built-in "Try it out" functionality.
+The `fidesctl` API is exceedingly formulaic, so much so that it's easier to grasp the API by understanding the formula, rather than reading through a list of endpoints. The fundamental idea is that there's a set of five endpoints for each Fides resource. These endpoints let you...
 
-Below, we've embedded the latest release's API documentation as a living reference. These work largely the same, but since this documentation site isn't connected to a live instance, the "Try it out" and "Authorize" buttons won't work, sorry!
+| Purpose | Example | Success code |
+| --- | --- | --- |
+| Create an instance of a particular resource type. | `POST /policy` | `201` |
+| Retrieve all instances of a resource type. | `GET /policy` | `200` |
+| Retrieve the resource identified by the `fides_key` path parameter. |`GET /policy/{fides_key}` | `200`|
+| Completely overwrite the `fides_key` resource.  |`POST /policy/{fides_key}`| `200` |
+| Delete the `fides_key` resource. | `DELETE /policy/{fides_key}`| `204`|
 
-## Swagger API Docs
+* The URLs of the endpoints emulate the names of the resources: `/organization`, `/policy`, `/registry`, `/system`, `/dataset`, `/data_category`, `/data_use`, `/data_subject`, `/data_qualifier`.
+
+* Except for the `DELETE`, the endpoints accept and/or return JSON objects that represent the named resource. The structure of these objects is given in the [Fides Language: Resources chapter](../language/resources.html) -- it's the same structure that's used in the resource manifest files. 
+
+That's about all there is to it. There are an additional four endpoints that we'll look at below, but the sets of quintuplet endpoints listed above make up the core of the `fidesctl` API. 
+
+After a brief review of the four addition endpoints, we'll provide a complete API reference followed by a set of cURL calls that you can use to exercise the API on your system.
+
+
+## Other endpoints
+
+The four additional endpoints are:
+
+* `GET /health` pings the API server to see if it's up and running. The call returns `200` if it's up and ready to receive messages, and `404` if not.
+
+* Three of the taxonomic resources, `/data_category`, `/data_use`, and `/data_qualifier` (but  _not_ `/data_subject`) define a `GET /resource_type/visualize/{figure_type}` endpoint that returns a graph of the resource's taxonomy.  For details, see the **API Reference**, below.
+
+
+## API Reference
 ---
-!!swagger openapi.json!!
+!!swagger openapi.json!!
+
+## cURL Calls

docs/fides/docs/css/fides.css

@@ -2,6 +2,9 @@ body {
   font-family: 'Source Sans Pro', sans-serif !important;
 }
 
+td {
+  font-size: 16px;
+}
 .md-header {
   background-color: #0861ce;
 }
@@ -40,7 +43,7 @@ body {
 .md-button.md-button--secondary.md-button-github:hover {
   padding-left: 60px;
   background: rgb(64, 81, 181) url('../img/sprites.png') no-repeat 5px -45px;
-  background-size: 35px 
+  background-size: 35px
 }
 .md-button.md-button--secondary.md-button-slack {
   padding-left: 60px;
@@ -52,7 +55,7 @@ body {
   padding-left: 60px;
   background: rgb(64, 81, 181) url('../img/sprites.png') no-repeat 5px -141px;
   background-size: 35px
-  
+
 }
 .md-button.md-button--secondary.md-button-discord {
   padding-left: 60px;
@@ -64,7 +67,7 @@ body {
   padding-left: 60px;
   background: rgb(64, 81, 181) url('../img/sprites.png') no-repeat 5px -225px;
   background-size: 35px
-  
+
 }
 
 .md-typeset__table{
@@ -88,7 +91,7 @@ body {
   color: #313f4e;
   margin: 0 auto;
   }
-  
+
 .vis h1 {
   font-weight: 700;
   font-size: 26px;
@@ -279,4 +282,4 @@ body {
 [data-md-color-scheme="slate"] .md-content h1,
 [data-md-color-scheme="slate"] .md-content h2 {
   color: white;
-}
+}

docs/fides/docs/css/swagger_override.css

@@ -0,0 +1,65 @@
+
+/* -- Swagger UI redesign -- */
+
+.renderedMarkdown p {
+  margin:  0px !important;
+  font-size:  16px !important;
+  font-family: 'Source Sans Pro', sans-serif !important;
+
+}
+.models, [data-tag="Visualize"], [href="openapi.json"], .response-col_links, .response-controls, .tab, select{
+  display:  none !important;
+  padding:  0px !important;
+  margin:  0px !important;
+}
+
+tbody .response-col_status {
+  font-size: 16px !important;
+  font-weight:  bold !important;
+}
+
+.col_header {
+  font-size: 16px !important;
+  font-weight:  bold !important;
+}
+
+.response-col_description p {
+  margin: 0px !important;
+}
+.opblock-summary-description {
+  font-size: 16px !important;
+}
+
+.model-example{
+  margin:  0px !important;
+}
+
+.tab {
+  margin:  4px !important;
+}
+
+.tabitem {
+  margin:  4px !important;
+  font-size:  14px !important;
+}
+
+/* Get rid of the harsh lime green */
+[style="color: rgb(162, 252, 162);"] {
+  color: inherit !important;
+}
+
+.microlight {
+  padding: 1px !important;
+}
+
+.info {
+  margin: 12px 12px 12px 0px !important;
+}
+
+.opblock-tag {
+  padding: 12px 0px 12px 0px !important;
+}
+
+span:after {
+  background:  none !important;
+}

docs/fides/docs/js/vis.js

@@ -1,3 +1,5 @@
+
+
 var VisColorLegend = class VisColorLegend {
   constructor({ el }) {
     this.el = el;

docs/fides/mkdocs.yml

@@ -30,8 +30,8 @@ nav:
         - Data Subjects: language/taxonomy/data_subjects.md
         - Data Qualifiers: language/taxonomy/data_qualifiers.md
   - CLI:
-    - fidesctl CLI Overview: cli/cli.md
-    - fidesctl Configuration File: cli/configuration-file
+    - CLI Overview: cli/cli.md
+    - Configuration File: cli/configuration-file
     - apply: cli/apply.md
     - delete: cli/delete.md
     - evaluate: cli/evaluate.md
@@ -94,6 +94,7 @@ extra_javascript:
 extra_css:
   - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.7.2/styles/default.min.css
   - css/fides.css
+  - css/swagger_override.css
 
 plugins:
   - render_swagger