diff --git a/docs/fides/docs/api/index.md b/docs/fides/docs/api/index.md index bea302a4d3..1104f7d4ba 100644 --- a/docs/fides/docs/api/index.md +++ b/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!! \ No newline at end of file +!!swagger openapi.json!! + +## cURL Calls diff --git a/docs/fides/docs/api/openapi.json b/docs/fides/docs/api/openapi.json new file mode 100644 index 0000000000..c5ebe60de1 --- /dev/null +++ b/docs/fides/docs/api/openapi.json @@ -0,0 +1,3172 @@ +{ + "openapi": "3.0.2", + "info": { + "title": "Fidesctl API", + "version": "0.1.0" + }, + "paths": { + "/health": { + "get": { + "tags": [ + "Healthcheck" + ], + "summary": "Healthcheck", + "description": "Define a simple healthcheck endpoint that will confirm if the API is running.", + "operationId": "healthcheck_health_get", + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": {} + } + } + } + } + } + }, + "/data_category/": { + "get": { + "tags": [ + "DataCategory" + ], + "summary": "List", + "description": "Get a list of all of the resources of this type.", + "operationId": "List_data_category__get", + "parameters": [ + { + "required": false, + "schema": { + "title": "Resource Type", + "type": "string", + "default": "data_category" + }, + "name": "resource_type", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "title": "Response List Data Category Get", + "type": "array", + "items": { + "$ref": "#/components/schemas/DataCategory" + } + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, + "post": { + "tags": [ + "DataCategory" + ], + "summary": "Create", + "description": "Create a resource.", + "operationId": "create_data_category__post", + "parameters": [ + { + "required": false, + "schema": { + "title": "Resource Type", + "type": "string", + "default": "data_category" + }, + "name": "resource_type", + "in": "query" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DataCategory" + } + } + }, + "required": true + }, + "responses": { + "201": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DataCategory" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/data_category/{fides_key}": { + "get": { + "tags": [ + "DataCategory" + ], + "summary": "Get", + "description": "Get a resource by its fides_key.", + "operationId": "get_data_category__fides_key__get", + "parameters": [ + { + "required": true, + "schema": { + "title": "Fides Key", + "type": "string" + }, + "name": "fides_key", + "in": "path" + }, + { + "required": false, + "schema": { + "title": "Resource Type", + "type": "string", + "default": "data_category" + }, + "name": "resource_type", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DataCategory" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, + "post": { + "tags": [ + "DataCategory" + ], + "summary": "Update", + "description": "Update a resource by its fides_key.", + "operationId": "update_data_category__fides_key__post", + "parameters": [ + { + "required": true, + "schema": { + "title": "Fides Key", + "type": "string" + }, + "name": "fides_key", + "in": "path" + }, + { + "required": false, + "schema": { + "title": "Resource Type", + "type": "string", + "default": "data_category" + }, + "name": "resource_type", + "in": "query" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DataCategory" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DataCategory" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, + "delete": { + "tags": [ + "DataCategory" + ], + "summary": "Delete", + "description": "Delete a resource by its fides_key.", + "operationId": "delete_data_category__fides_key__delete", + "parameters": [ + { + "required": true, + "schema": { + "title": "Fides Key", + "type": "string" + }, + "name": "fides_key", + "in": "path" + }, + { + "required": false, + "schema": { + "title": "Resource Type", + "type": "string", + "default": "data_category" + }, + "name": "resource_type", + "in": "query" + } + ], + "responses": { + "204": { + "description": "Successful Response" + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/data_qualifier/": { + "get": { + "tags": [ + "DataQualifier" + ], + "summary": "List", + "description": "Get a list of all of the resources of this type.", + "operationId": "List_data_qualifier__get", + "parameters": [ + { + "required": false, + "schema": { + "title": "Resource Type", + "type": "string", + "default": "data_qualifier" + }, + "name": "resource_type", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "title": "Response List Data Qualifier Get", + "type": "array", + "items": { + "$ref": "#/components/schemas/DataQualifier" + } + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, + "post": { + "tags": [ + "DataQualifier" + ], + "summary": "Create", + "description": "Create a resource.", + "operationId": "create_data_qualifier__post", + "parameters": [ + { + "required": false, + "schema": { + "title": "Resource Type", + "type": "string", + "default": "data_qualifier" + }, + "name": "resource_type", + "in": "query" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DataQualifier" + } + } + }, + "required": true + }, + "responses": { + "201": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DataQualifier" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/data_qualifier/{fides_key}": { + "get": { + "tags": [ + "DataQualifier" + ], + "summary": "Get", + "description": "Get a resource by its fides_key.", + "operationId": "get_data_qualifier__fides_key__get", + "parameters": [ + { + "required": true, + "schema": { + "title": "Fides Key", + "type": "string" + }, + "name": "fides_key", + "in": "path" + }, + { + "required": false, + "schema": { + "title": "Resource Type", + "type": "string", + "default": "data_qualifier" + }, + "name": "resource_type", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DataQualifier" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, + "post": { + "tags": [ + "DataQualifier" + ], + "summary": "Update", + "description": "Update a resource by its fides_key.", + "operationId": "update_data_qualifier__fides_key__post", + "parameters": [ + { + "required": true, + "schema": { + "title": "Fides Key", + "type": "string" + }, + "name": "fides_key", + "in": "path" + }, + { + "required": false, + "schema": { + "title": "Resource Type", + "type": "string", + "default": "data_qualifier" + }, + "name": "resource_type", + "in": "query" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DataQualifier" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DataQualifier" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, + "delete": { + "tags": [ + "DataQualifier" + ], + "summary": "Delete", + "description": "Delete a resource by its fides_key.", + "operationId": "delete_data_qualifier__fides_key__delete", + "parameters": [ + { + "required": true, + "schema": { + "title": "Fides Key", + "type": "string" + }, + "name": "fides_key", + "in": "path" + }, + { + "required": false, + "schema": { + "title": "Resource Type", + "type": "string", + "default": "data_qualifier" + }, + "name": "resource_type", + "in": "query" + } + ], + "responses": { + "204": { + "description": "Successful Response" + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/data_subject/": { + "get": { + "tags": [ + "DataSubject" + ], + "summary": "List", + "description": "Get a list of all of the resources of this type.", + "operationId": "List_data_subject__get", + "parameters": [ + { + "required": false, + "schema": { + "title": "Resource Type", + "type": "string", + "default": "data_subject" + }, + "name": "resource_type", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "title": "Response List Data Subject Get", + "type": "array", + "items": { + "$ref": "#/components/schemas/DataSubject" + } + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, + "post": { + "tags": [ + "DataSubject" + ], + "summary": "Create", + "description": "Create a resource.", + "operationId": "create_data_subject__post", + "parameters": [ + { + "required": false, + "schema": { + "title": "Resource Type", + "type": "string", + "default": "data_subject" + }, + "name": "resource_type", + "in": "query" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DataSubject" + } + } + }, + "required": true + }, + "responses": { + "201": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DataSubject" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/data_subject/{fides_key}": { + "get": { + "tags": [ + "DataSubject" + ], + "summary": "Get", + "description": "Get a resource by its fides_key.", + "operationId": "get_data_subject__fides_key__get", + "parameters": [ + { + "required": true, + "schema": { + "title": "Fides Key", + "type": "string" + }, + "name": "fides_key", + "in": "path" + }, + { + "required": false, + "schema": { + "title": "Resource Type", + "type": "string", + "default": "data_subject" + }, + "name": "resource_type", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DataSubject" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, + "post": { + "tags": [ + "DataSubject" + ], + "summary": "Update", + "description": "Update a resource by its fides_key.", + "operationId": "update_data_subject__fides_key__post", + "parameters": [ + { + "required": true, + "schema": { + "title": "Fides Key", + "type": "string" + }, + "name": "fides_key", + "in": "path" + }, + { + "required": false, + "schema": { + "title": "Resource Type", + "type": "string", + "default": "data_subject" + }, + "name": "resource_type", + "in": "query" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DataSubject" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DataSubject" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, + "delete": { + "tags": [ + "DataSubject" + ], + "summary": "Delete", + "description": "Delete a resource by its fides_key.", + "operationId": "delete_data_subject__fides_key__delete", + "parameters": [ + { + "required": true, + "schema": { + "title": "Fides Key", + "type": "string" + }, + "name": "fides_key", + "in": "path" + }, + { + "required": false, + "schema": { + "title": "Resource Type", + "type": "string", + "default": "data_subject" + }, + "name": "resource_type", + "in": "query" + } + ], + "responses": { + "204": { + "description": "Successful Response" + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/data_use/": { + "get": { + "tags": [ + "DataUse" + ], + "summary": "List", + "description": "Get a list of all of the resources of this type.", + "operationId": "List_data_use__get", + "parameters": [ + { + "required": false, + "schema": { + "title": "Resource Type", + "type": "string", + "default": "data_use" + }, + "name": "resource_type", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "title": "Response List Data Use Get", + "type": "array", + "items": { + "$ref": "#/components/schemas/DataUse" + } + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, + "post": { + "tags": [ + "DataUse" + ], + "summary": "Create", + "description": "Create a resource.", + "operationId": "create_data_use__post", + "parameters": [ + { + "required": false, + "schema": { + "title": "Resource Type", + "type": "string", + "default": "data_use" + }, + "name": "resource_type", + "in": "query" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DataUse" + } + } + }, + "required": true + }, + "responses": { + "201": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DataUse" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/data_use/{fides_key}": { + "get": { + "tags": [ + "DataUse" + ], + "summary": "Get", + "description": "Get a resource by its fides_key.", + "operationId": "get_data_use__fides_key__get", + "parameters": [ + { + "required": true, + "schema": { + "title": "Fides Key", + "type": "string" + }, + "name": "fides_key", + "in": "path" + }, + { + "required": false, + "schema": { + "title": "Resource Type", + "type": "string", + "default": "data_use" + }, + "name": "resource_type", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DataUse" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, + "post": { + "tags": [ + "DataUse" + ], + "summary": "Update", + "description": "Update a resource by its fides_key.", + "operationId": "update_data_use__fides_key__post", + "parameters": [ + { + "required": true, + "schema": { + "title": "Fides Key", + "type": "string" + }, + "name": "fides_key", + "in": "path" + }, + { + "required": false, + "schema": { + "title": "Resource Type", + "type": "string", + "default": "data_use" + }, + "name": "resource_type", + "in": "query" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DataUse" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DataUse" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, + "delete": { + "tags": [ + "DataUse" + ], + "summary": "Delete", + "description": "Delete a resource by its fides_key.", + "operationId": "delete_data_use__fides_key__delete", + "parameters": [ + { + "required": true, + "schema": { + "title": "Fides Key", + "type": "string" + }, + "name": "fides_key", + "in": "path" + }, + { + "required": false, + "schema": { + "title": "Resource Type", + "type": "string", + "default": "data_use" + }, + "name": "resource_type", + "in": "query" + } + ], + "responses": { + "204": { + "description": "Successful Response" + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/dataset/": { + "get": { + "tags": [ + "Dataset" + ], + "summary": "List", + "description": "Get a list of all of the resources of this type.", + "operationId": "List_dataset__get", + "parameters": [ + { + "required": false, + "schema": { + "title": "Resource Type", + "type": "string", + "default": "dataset" + }, + "name": "resource_type", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "title": "Response List Dataset Get", + "type": "array", + "items": { + "$ref": "#/components/schemas/Dataset" + } + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, + "post": { + "tags": [ + "Dataset" + ], + "summary": "Create", + "description": "Create a resource.", + "operationId": "create_dataset__post", + "parameters": [ + { + "required": false, + "schema": { + "title": "Resource Type", + "type": "string", + "default": "dataset" + }, + "name": "resource_type", + "in": "query" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Dataset" + } + } + }, + "required": true + }, + "responses": { + "201": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Dataset" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/dataset/{fides_key}": { + "get": { + "tags": [ + "Dataset" + ], + "summary": "Get", + "description": "Get a resource by its fides_key.", + "operationId": "get_dataset__fides_key__get", + "parameters": [ + { + "required": true, + "schema": { + "title": "Fides Key", + "type": "string" + }, + "name": "fides_key", + "in": "path" + }, + { + "required": false, + "schema": { + "title": "Resource Type", + "type": "string", + "default": "dataset" + }, + "name": "resource_type", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Dataset" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, + "post": { + "tags": [ + "Dataset" + ], + "summary": "Update", + "description": "Update a resource by its fides_key.", + "operationId": "update_dataset__fides_key__post", + "parameters": [ + { + "required": true, + "schema": { + "title": "Fides Key", + "type": "string" + }, + "name": "fides_key", + "in": "path" + }, + { + "required": false, + "schema": { + "title": "Resource Type", + "type": "string", + "default": "dataset" + }, + "name": "resource_type", + "in": "query" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Dataset" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Dataset" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, + "delete": { + "tags": [ + "Dataset" + ], + "summary": "Delete", + "description": "Delete a resource by its fides_key.", + "operationId": "delete_dataset__fides_key__delete", + "parameters": [ + { + "required": true, + "schema": { + "title": "Fides Key", + "type": "string" + }, + "name": "fides_key", + "in": "path" + }, + { + "required": false, + "schema": { + "title": "Resource Type", + "type": "string", + "default": "dataset" + }, + "name": "resource_type", + "in": "query" + } + ], + "responses": { + "204": { + "description": "Successful Response" + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/organization/": { + "get": { + "tags": [ + "Organization" + ], + "summary": "List", + "description": "Get a list of all of the resources of this type.", + "operationId": "List_organization__get", + "parameters": [ + { + "required": false, + "schema": { + "title": "Resource Type", + "type": "string", + "default": "organization" + }, + "name": "resource_type", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "title": "Response List Organization Get", + "type": "array", + "items": { + "$ref": "#/components/schemas/Organization" + } + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, + "post": { + "tags": [ + "Organization" + ], + "summary": "Create", + "description": "Create a resource.", + "operationId": "create_organization__post", + "parameters": [ + { + "required": false, + "schema": { + "title": "Resource Type", + "type": "string", + "default": "organization" + }, + "name": "resource_type", + "in": "query" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Organization" + } + } + }, + "required": true + }, + "responses": { + "201": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Organization" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/organization/{fides_key}": { + "get": { + "tags": [ + "Organization" + ], + "summary": "Get", + "description": "Get a resource by its fides_key.", + "operationId": "get_organization__fides_key__get", + "parameters": [ + { + "required": true, + "schema": { + "title": "Fides Key", + "type": "string" + }, + "name": "fides_key", + "in": "path" + }, + { + "required": false, + "schema": { + "title": "Resource Type", + "type": "string", + "default": "organization" + }, + "name": "resource_type", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Organization" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, + "post": { + "tags": [ + "Organization" + ], + "summary": "Update", + "description": "Update a resource by its fides_key.", + "operationId": "update_organization__fides_key__post", + "parameters": [ + { + "required": true, + "schema": { + "title": "Fides Key", + "type": "string" + }, + "name": "fides_key", + "in": "path" + }, + { + "required": false, + "schema": { + "title": "Resource Type", + "type": "string", + "default": "organization" + }, + "name": "resource_type", + "in": "query" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Organization" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Organization" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, + "delete": { + "tags": [ + "Organization" + ], + "summary": "Delete", + "description": "Delete a resource by its fides_key.", + "operationId": "delete_organization__fides_key__delete", + "parameters": [ + { + "required": true, + "schema": { + "title": "Fides Key", + "type": "string" + }, + "name": "fides_key", + "in": "path" + }, + { + "required": false, + "schema": { + "title": "Resource Type", + "type": "string", + "default": "organization" + }, + "name": "resource_type", + "in": "query" + } + ], + "responses": { + "204": { + "description": "Successful Response" + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/policy/": { + "get": { + "tags": [ + "Policy" + ], + "summary": "List", + "description": "Get a list of all of the resources of this type.", + "operationId": "List_policy__get", + "parameters": [ + { + "required": false, + "schema": { + "title": "Resource Type", + "type": "string", + "default": "policy" + }, + "name": "resource_type", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "title": "Response List Policy Get", + "type": "array", + "items": { + "$ref": "#/components/schemas/Policy" + } + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, + "post": { + "tags": [ + "Policy" + ], + "summary": "Create", + "description": "Create a resource.", + "operationId": "create_policy__post", + "parameters": [ + { + "required": false, + "schema": { + "title": "Resource Type", + "type": "string", + "default": "policy" + }, + "name": "resource_type", + "in": "query" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Policy" + } + } + }, + "required": true + }, + "responses": { + "201": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Policy" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/policy/{fides_key}": { + "get": { + "tags": [ + "Policy" + ], + "summary": "Get", + "description": "Get a resource by its fides_key.", + "operationId": "get_policy__fides_key__get", + "parameters": [ + { + "required": true, + "schema": { + "title": "Fides Key", + "type": "string" + }, + "name": "fides_key", + "in": "path" + }, + { + "required": false, + "schema": { + "title": "Resource Type", + "type": "string", + "default": "policy" + }, + "name": "resource_type", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Policy" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, + "post": { + "tags": [ + "Policy" + ], + "summary": "Update", + "description": "Update a resource by its fides_key.", + "operationId": "update_policy__fides_key__post", + "parameters": [ + { + "required": true, + "schema": { + "title": "Fides Key", + "type": "string" + }, + "name": "fides_key", + "in": "path" + }, + { + "required": false, + "schema": { + "title": "Resource Type", + "type": "string", + "default": "policy" + }, + "name": "resource_type", + "in": "query" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Policy" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Policy" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, + "delete": { + "tags": [ + "Policy" + ], + "summary": "Delete", + "description": "Delete a resource by its fides_key.", + "operationId": "delete_policy__fides_key__delete", + "parameters": [ + { + "required": true, + "schema": { + "title": "Fides Key", + "type": "string" + }, + "name": "fides_key", + "in": "path" + }, + { + "required": false, + "schema": { + "title": "Resource Type", + "type": "string", + "default": "policy" + }, + "name": "resource_type", + "in": "query" + } + ], + "responses": { + "204": { + "description": "Successful Response" + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/registry/": { + "get": { + "tags": [ + "Registry" + ], + "summary": "List", + "description": "Get a list of all of the resources of this type.", + "operationId": "List_registry__get", + "parameters": [ + { + "required": false, + "schema": { + "title": "Resource Type", + "type": "string", + "default": "registry" + }, + "name": "resource_type", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "title": "Response List Registry Get", + "type": "array", + "items": { + "$ref": "#/components/schemas/Registry" + } + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, + "post": { + "tags": [ + "Registry" + ], + "summary": "Create", + "description": "Create a resource.", + "operationId": "create_registry__post", + "parameters": [ + { + "required": false, + "schema": { + "title": "Resource Type", + "type": "string", + "default": "registry" + }, + "name": "resource_type", + "in": "query" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Registry" + } + } + }, + "required": true + }, + "responses": { + "201": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Registry" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/registry/{fides_key}": { + "get": { + "tags": [ + "Registry" + ], + "summary": "Get", + "description": "Get a resource by its fides_key.", + "operationId": "get_registry__fides_key__get", + "parameters": [ + { + "required": true, + "schema": { + "title": "Fides Key", + "type": "string" + }, + "name": "fides_key", + "in": "path" + }, + { + "required": false, + "schema": { + "title": "Resource Type", + "type": "string", + "default": "registry" + }, + "name": "resource_type", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Registry" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, + "post": { + "tags": [ + "Registry" + ], + "summary": "Update", + "description": "Update a resource by its fides_key.", + "operationId": "update_registry__fides_key__post", + "parameters": [ + { + "required": true, + "schema": { + "title": "Fides Key", + "type": "string" + }, + "name": "fides_key", + "in": "path" + }, + { + "required": false, + "schema": { + "title": "Resource Type", + "type": "string", + "default": "registry" + }, + "name": "resource_type", + "in": "query" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Registry" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Registry" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, + "delete": { + "tags": [ + "Registry" + ], + "summary": "Delete", + "description": "Delete a resource by its fides_key.", + "operationId": "delete_registry__fides_key__delete", + "parameters": [ + { + "required": true, + "schema": { + "title": "Fides Key", + "type": "string" + }, + "name": "fides_key", + "in": "path" + }, + { + "required": false, + "schema": { + "title": "Resource Type", + "type": "string", + "default": "registry" + }, + "name": "resource_type", + "in": "query" + } + ], + "responses": { + "204": { + "description": "Successful Response" + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/system/": { + "get": { + "tags": [ + "System" + ], + "summary": "List", + "description": "Get a list of all of the resources of this type.", + "operationId": "List_system__get", + "parameters": [ + { + "required": false, + "schema": { + "title": "Resource Type", + "type": "string", + "default": "system" + }, + "name": "resource_type", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "title": "Response List System Get", + "type": "array", + "items": { + "$ref": "#/components/schemas/System" + } + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, + "post": { + "tags": [ + "System" + ], + "summary": "Create", + "description": "Create a resource.", + "operationId": "create_system__post", + "parameters": [ + { + "required": false, + "schema": { + "title": "Resource Type", + "type": "string", + "default": "system" + }, + "name": "resource_type", + "in": "query" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/System" + } + } + }, + "required": true + }, + "responses": { + "201": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/System" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/system/{fides_key}": { + "get": { + "tags": [ + "System" + ], + "summary": "Get", + "description": "Get a resource by its fides_key.", + "operationId": "get_system__fides_key__get", + "parameters": [ + { + "required": true, + "schema": { + "title": "Fides Key", + "type": "string" + }, + "name": "fides_key", + "in": "path" + }, + { + "required": false, + "schema": { + "title": "Resource Type", + "type": "string", + "default": "system" + }, + "name": "resource_type", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/System" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, + "post": { + "tags": [ + "System" + ], + "summary": "Update", + "description": "Update a resource by its fides_key.", + "operationId": "update_system__fides_key__post", + "parameters": [ + { + "required": true, + "schema": { + "title": "Fides Key", + "type": "string" + }, + "name": "fides_key", + "in": "path" + }, + { + "required": false, + "schema": { + "title": "Resource Type", + "type": "string", + "default": "system" + }, + "name": "resource_type", + "in": "query" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/System" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/System" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, + "delete": { + "tags": [ + "System" + ], + "summary": "Delete", + "description": "Delete a resource by its fides_key.", + "operationId": "delete_system__fides_key__delete", + "parameters": [ + { + "required": true, + "schema": { + "title": "Fides Key", + "type": "string" + }, + "name": "fides_key", + "in": "path" + }, + { + "required": false, + "schema": { + "title": "Resource Type", + "type": "string", + "default": "system" + }, + "name": "resource_type", + "in": "query" + } + ], + "responses": { + "204": { + "description": "Successful Response" + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/data_category/visualize/{figure_type}": { + "get": { + "tags": [ + "Visualize", + "DataCategory" + ], + "summary": "Get Visualization", + "description": " Visualize the hierarchy of a supported resource type.\nArgs:\n figure_type: type of figure, by name, to generate\n resource_type: hierarchy source. one of [\"data_category\", \"data_qualifier\", \"data_use\"]\n\nReturns:\n Html for the requested figure. Response with status code 400 when invalid figure type is provided", + "operationId": "get_visualization_data_category_visualize__figure_type__get", + "parameters": [ + { + "required": true, + "schema": { + "$ref": "#/components/schemas/FigureTypeEnum" + }, + "name": "figure_type", + "in": "path" + }, + { + "required": false, + "schema": { + "title": "Resource Type", + "type": "string", + "default": "data_category" + }, + "name": "resource_type", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": {} + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/data_qualifier/visualize/{figure_type}": { + "get": { + "tags": [ + "Visualize", + "DataQualifier" + ], + "summary": "Get Visualization", + "description": " Visualize the hierarchy of a supported resource type.\nArgs:\n figure_type: type of figure, by name, to generate\n resource_type: hierarchy source. one of [\"data_category\", \"data_qualifier\", \"data_use\"]\n\nReturns:\n Html for the requested figure. Response with status code 400 when invalid figure type is provided", + "operationId": "get_visualization_data_qualifier_visualize__figure_type__get", + "parameters": [ + { + "required": true, + "schema": { + "$ref": "#/components/schemas/FigureTypeEnum" + }, + "name": "figure_type", + "in": "path" + }, + { + "required": false, + "schema": { + "title": "Resource Type", + "type": "string", + "default": "data_qualifier" + }, + "name": "resource_type", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": {} + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/data_use/visualize/{figure_type}": { + "get": { + "tags": [ + "Visualize", + "DataUse" + ], + "summary": "Get Visualization", + "description": " Visualize the hierarchy of a supported resource type.\nArgs:\n figure_type: type of figure, by name, to generate\n resource_type: hierarchy source. one of [\"data_category\", \"data_qualifier\", \"data_use\"]\n\nReturns:\n Html for the requested figure. Response with status code 400 when invalid figure type is provided", + "operationId": "get_visualization_data_use_visualize__figure_type__get", + "parameters": [ + { + "required": true, + "schema": { + "$ref": "#/components/schemas/FigureTypeEnum" + }, + "name": "figure_type", + "in": "path" + }, + { + "required": false, + "schema": { + "title": "Resource Type", + "type": "string", + "default": "data_use" + }, + "name": "resource_type", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": {} + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + } + }, + "components": { + "schemas": { + "ActionEnum": { + "title": "ActionEnum", + "enum": [ + "ACCEPT", + "REJECT", + "REQUIRE" + ], + "type": "string", + "description": "The ActionEnum resource model.\n\nDescribes what the result of the PolicyRule should be if it is fulfilled." + }, + "DataCategory": { + "title": "DataCategory", + "required": [ + "fides_key" + ], + "type": "object", + "properties": { + "fides_key": { + "title": "Fides Key", + "pattern": "^[a-zA-Z0-9_.]+$", + "type": "string", + "description": "A unique key used to identify this resource." + }, + "organization_fides_key": { + "title": "Organization Fides Key", + "pattern": "^[a-zA-Z0-9_.]+$", + "type": "string", + "description": "Defines the Organization that this resource belongs to.", + "default": "default_organization" + }, + "name": { + "title": "Name", + "type": "string", + "description": "Human-Readable string name for this resource." + }, + "description": { + "title": "Description", + "type": "string", + "description": "In-depth description of what this resource is." + }, + "parent_key": { + "title": "Parent Key", + "pattern": "^[a-zA-Z0-9_.]+$", + "type": "string" + } + }, + "description": "The DataCategory resource model." + }, + "DataQualifier": { + "title": "DataQualifier", + "required": [ + "fides_key" + ], + "type": "object", + "properties": { + "fides_key": { + "title": "Fides Key", + "pattern": "^[a-zA-Z0-9_.]+$", + "type": "string", + "description": "A unique key used to identify this resource." + }, + "organization_fides_key": { + "title": "Organization Fides Key", + "pattern": "^[a-zA-Z0-9_.]+$", + "type": "string", + "description": "Defines the Organization that this resource belongs to.", + "default": "default_organization" + }, + "name": { + "title": "Name", + "type": "string", + "description": "Human-Readable string name for this resource." + }, + "description": { + "title": "Description", + "type": "string", + "description": "In-depth description of what this resource is." + }, + "parent_key": { + "title": "Parent Key", + "pattern": "^[a-zA-Z0-9_.]+$", + "type": "string" + } + }, + "description": "The DataQualifier resource model." + }, + "DataSubject": { + "title": "DataSubject", + "required": [ + "fides_key" + ], + "type": "object", + "properties": { + "fides_key": { + "title": "Fides Key", + "pattern": "^[a-zA-Z0-9_.]+$", + "type": "string", + "description": "A unique key used to identify this resource." + }, + "organization_fides_key": { + "title": "Organization Fides Key", + "pattern": "^[a-zA-Z0-9_.]+$", + "type": "string", + "description": "Defines the Organization that this resource belongs to.", + "default": "default_organization" + }, + "name": { + "title": "Name", + "type": "string", + "description": "Human-Readable string name for this resource." + }, + "description": { + "title": "Description", + "type": "string", + "description": "In-depth description of what this resource is." + } + }, + "description": "The DataSubject resource model." + }, + "DataUse": { + "title": "DataUse", + "required": [ + "fides_key" + ], + "type": "object", + "properties": { + "fides_key": { + "title": "Fides Key", + "pattern": "^[a-zA-Z0-9_.]+$", + "type": "string", + "description": "A unique key used to identify this resource." + }, + "organization_fides_key": { + "title": "Organization Fides Key", + "pattern": "^[a-zA-Z0-9_.]+$", + "type": "string", + "description": "Defines the Organization that this resource belongs to.", + "default": "default_organization" + }, + "name": { + "title": "Name", + "type": "string", + "description": "Human-Readable string name for this resource." + }, + "description": { + "title": "Description", + "type": "string", + "description": "In-depth description of what this resource is." + }, + "parent_key": { + "title": "Parent Key", + "pattern": "^[a-zA-Z0-9_.]+$", + "type": "string" + } + }, + "description": "The DataUse resource model." + }, + "Dataset": { + "title": "Dataset", + "required": [ + "fides_key", + "collections" + ], + "type": "object", + "properties": { + "fides_key": { + "title": "Fides Key", + "pattern": "^[a-zA-Z0-9_.]+$", + "type": "string", + "description": "A unique key used to identify this resource." + }, + "organization_fides_key": { + "title": "Organization Fides Key", + "pattern": "^[a-zA-Z0-9_.]+$", + "type": "string", + "description": "Defines the Organization that this resource belongs to.", + "default": "default_organization" + }, + "name": { + "title": "Name", + "type": "string", + "description": "Human-Readable string name for this resource." + }, + "description": { + "title": "Description", + "type": "string", + "description": "In-depth description of what this resource is." + }, + "meta": { + "title": "Meta", + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "data_categories": { + "title": "Data Categories", + "type": "array", + "items": { + "pattern": "^[a-zA-Z0-9_.]+$", + "type": "string" + } + }, + "data_qualifiers": { + "title": "Data Qualifiers", + "type": "array", + "items": { + "pattern": "^[a-zA-Z0-9_.]+$", + "type": "string" + }, + "default": [ + "aggregated.anonymized.unlinked_pseudonymized.pseudonymized.identified" + ] + }, + "collections": { + "title": "Collections", + "type": "array", + "items": { + "$ref": "#/components/schemas/DatasetCollection" + } + } + }, + "description": "The Dataset resource model." + }, + "DatasetCollection": { + "title": "DatasetCollection", + "required": [ + "name", + "fields" + ], + "type": "object", + "properties": { + "name": { + "title": "Name", + "type": "string" + }, + "description": { + "title": "Description", + "type": "string" + }, + "data_categories": { + "title": "Data Categories", + "type": "array", + "items": { + "pattern": "^[a-zA-Z0-9_.]+$", + "type": "string" + } + }, + "data_qualifiers": { + "title": "Data Qualifiers", + "type": "array", + "items": { + "pattern": "^[a-zA-Z0-9_.]+$", + "type": "string" + }, + "default": [ + "aggregated.anonymized.unlinked_pseudonymized.pseudonymized.identified" + ] + }, + "fields": { + "title": "Fields", + "type": "array", + "items": { + "$ref": "#/components/schemas/DatasetField" + } + } + }, + "description": "The DatasetCollection resource model.\n\nThis resource is nested witin a Dataset." + }, + "DatasetField": { + "title": "DatasetField", + "required": [ + "name" + ], + "type": "object", + "properties": { + "name": { + "title": "Name", + "type": "string" + }, + "description": { + "title": "Description", + "type": "string" + }, + "data_categories": { + "title": "Data Categories", + "type": "array", + "items": { + "pattern": "^[a-zA-Z0-9_.]+$", + "type": "string" + } + }, + "data_qualifier": { + "title": "Data Qualifier", + "pattern": "^[a-zA-Z0-9_.]+$", + "type": "string", + "default": "aggregated.anonymized.unlinked_pseudonymized.pseudonymized.identified" + } + }, + "description": "The DatasetField resource model.\n\nThis resource is nested within a DatasetCollection." + }, + "FigureTypeEnum": { + "title": "FigureTypeEnum", + "enum": [ + "sankey", + "sunburst", + "text" + ], + "type": "string", + "description": "Figure Type Enum to capture the discrete possible values\nfor a valid figure type to be visualized" + }, + "HTTPValidationError": { + "title": "HTTPValidationError", + "type": "object", + "properties": { + "detail": { + "title": "Detail", + "type": "array", + "items": { + "$ref": "#/components/schemas/ValidationError" + } + } + } + }, + "InclusionEnum": { + "title": "InclusionEnum", + "enum": [ + "ANY", + "ALL", + "NONE" + ], + "type": "string", + "description": "The InclusionEnum resouce model.\n\nDetermines how the listed resources are included in the evaluation logic." + }, + "Organization": { + "title": "Organization", + "required": [ + "fides_key" + ], + "type": "object", + "properties": { + "fides_key": { + "title": "Fides Key", + "pattern": "^[a-zA-Z0-9_.]+$", + "type": "string", + "description": "A unique key used to identify this resource." + }, + "organization_fides_key": { + "title": "Organization Fides Key", + "pattern": "^[a-zA-Z0-9_.]+$", + "type": "string", + "description": "Defines the Organization that this resource belongs to.", + "default": "default_organization" + }, + "name": { + "title": "Name", + "type": "string", + "description": "Human-Readable string name for this resource." + }, + "description": { + "title": "Description", + "type": "string", + "description": "In-depth description of what this resource is." + }, + "organiztion_parent_key": { + "title": "Organiztion Parent Key", + "type": "null" + } + }, + "description": "The Organization resource model.\n\nThis resource is used as a way to organize all other resources." + }, + "Policy": { + "title": "Policy", + "required": [ + "fides_key", + "rules" + ], + "type": "object", + "properties": { + "fides_key": { + "title": "Fides Key", + "pattern": "^[a-zA-Z0-9_.]+$", + "type": "string", + "description": "A unique key used to identify this resource." + }, + "organization_fides_key": { + "title": "Organization Fides Key", + "pattern": "^[a-zA-Z0-9_.]+$", + "type": "string", + "description": "Defines the Organization that this resource belongs to.", + "default": "default_organization" + }, + "name": { + "title": "Name", + "type": "string", + "description": "Human-Readable string name for this resource." + }, + "description": { + "title": "Description", + "type": "string", + "description": "In-depth description of what this resource is." + }, + "rules": { + "title": "Rules", + "type": "array", + "items": { + "$ref": "#/components/schemas/PolicyRule" + } + } + }, + "description": "The Policy resource model.\n\nAn object used to organize a list of PolicyRules." + }, + "PolicyRule": { + "title": "PolicyRule", + "required": [ + "fides_key", + "data_categories", + "data_uses", + "data_subjects", + "action" + ], + "type": "object", + "properties": { + "fides_key": { + "title": "Fides Key", + "pattern": "^[a-zA-Z0-9_.]+$", + "type": "string", + "description": "A unique key used to identify this resource." + }, + "organization_fides_key": { + "title": "Organization Fides Key", + "pattern": "^[a-zA-Z0-9_.]+$", + "type": "string", + "description": "Defines the Organization that this resource belongs to.", + "default": "default_organization" + }, + "name": { + "title": "Name", + "type": "string", + "description": "Human-Readable string name for this resource." + }, + "description": { + "title": "Description", + "type": "string", + "description": "In-depth description of what this resource is." + }, + "data_categories": { + "$ref": "#/components/schemas/PrivacyRule" + }, + "data_uses": { + "$ref": "#/components/schemas/PrivacyRule" + }, + "data_subjects": { + "$ref": "#/components/schemas/PrivacyRule" + }, + "data_qualifier": { + "title": "Data Qualifier", + "pattern": "^[a-zA-Z0-9_.]+$", + "type": "string", + "default": "aggregated.anonymized.unlinked_pseudonymized.pseudonymized.identified" + }, + "action": { + "$ref": "#/components/schemas/ActionEnum" + } + }, + "description": "The PolicyRule resource model.\n\nDescribes combination of the various types of privacy data types\nand what action that combination constitutes." + }, + "PrivacyDeclaration": { + "title": "PrivacyDeclaration", + "required": [ + "name", + "data_categories", + "data_use", + "data_subjects" + ], + "type": "object", + "properties": { + "name": { + "title": "Name", + "type": "string" + }, + "data_categories": { + "title": "Data Categories", + "type": "array", + "items": { + "pattern": "^[a-zA-Z0-9_.]+$", + "type": "string" + } + }, + "data_use": { + "title": "Data Use", + "pattern": "^[a-zA-Z0-9_.]+$", + "type": "string" + }, + "data_qualifier": { + "title": "Data Qualifier", + "pattern": "^[a-zA-Z0-9_.]+$", + "type": "string", + "default": "aggregated.anonymized.unlinked_pseudonymized.pseudonymized.identified" + }, + "data_subjects": { + "title": "Data Subjects", + "type": "array", + "items": { + "pattern": "^[a-zA-Z0-9_.]+$", + "type": "string" + } + }, + "dataset_references": { + "title": "Dataset References", + "type": "array", + "items": { + "type": "string" + } + } + }, + "description": "The PrivacyDeclaration resource model.\n\nStates a function of a system, and describes how it relates\nto the privacy data types." + }, + "PrivacyRule": { + "title": "PrivacyRule", + "required": [ + "inclusion", + "values" + ], + "type": "object", + "properties": { + "inclusion": { + "$ref": "#/components/schemas/InclusionEnum" + }, + "values": { + "title": "Values", + "type": "array", + "items": { + "pattern": "^[a-zA-Z0-9_.]+$", + "type": "string" + } + } + }, + "description": "The PrivacyRule resource model.\n\nA list of privacy data types and what inclusion method to use." + }, + "Registry": { + "title": "Registry", + "required": [ + "fides_key" + ], + "type": "object", + "properties": { + "fides_key": { + "title": "Fides Key", + "pattern": "^[a-zA-Z0-9_.]+$", + "type": "string", + "description": "A unique key used to identify this resource." + }, + "organization_fides_key": { + "title": "Organization Fides Key", + "pattern": "^[a-zA-Z0-9_.]+$", + "type": "string", + "description": "Defines the Organization that this resource belongs to.", + "default": "default_organization" + }, + "name": { + "title": "Name", + "type": "string", + "description": "Human-Readable string name for this resource." + }, + "description": { + "title": "Description", + "type": "string", + "description": "In-depth description of what this resource is." + } + }, + "description": "The Registry resource model.\n\nSystems can be assigned to this resource, but it doesn't inherently\npoint to any other resources." + }, + "System": { + "title": "System", + "required": [ + "fides_key", + "system_type", + "privacy_declarations" + ], + "type": "object", + "properties": { + "fides_key": { + "title": "Fides Key", + "pattern": "^[a-zA-Z0-9_.]+$", + "type": "string", + "description": "A unique key used to identify this resource." + }, + "organization_fides_key": { + "title": "Organization Fides Key", + "pattern": "^[a-zA-Z0-9_.]+$", + "type": "string", + "description": "Defines the Organization that this resource belongs to.", + "default": "default_organization" + }, + "name": { + "title": "Name", + "type": "string", + "description": "Human-Readable string name for this resource." + }, + "description": { + "title": "Description", + "type": "string", + "description": "In-depth description of what this resource is." + }, + "registry_id": { + "title": "Registry Id", + "type": "integer" + }, + "meta": { + "title": "Meta", + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "system_type": { + "title": "System Type", + "type": "string" + }, + "privacy_declarations": { + "title": "Privacy Declarations", + "type": "array", + "items": { + "$ref": "#/components/schemas/PrivacyDeclaration" + } + }, + "system_dependencies": { + "title": "System Dependencies", + "type": "array", + "items": { + "pattern": "^[a-zA-Z0-9_.]+$", + "type": "string" + } + } + }, + "description": "The System resource model.\n\nDescribes an application and includes a list of PrivacyDeclaration resources." + }, + "ValidationError": { + "title": "ValidationError", + "required": [ + "loc", + "msg", + "type" + ], + "type": "object", + "properties": { + "loc": { + "title": "Location", + "type": "array", + "items": { + "type": "string" + } + }, + "msg": { + "title": "Message", + "type": "string" + }, + "type": { + "title": "Error Type", + "type": "string" + } + } + } + } + } +} \ No newline at end of file diff --git a/docs/fides/docs/cli.md b/docs/fides/docs/cli.md deleted file mode 100644 index 91d55ad898..0000000000 --- a/docs/fides/docs/cli.md +++ /dev/null @@ -1,19 +0,0 @@ -# Fidesctl CLI - ---- - -The Fidesctl CLI wraps the entire functionality of Fidesctl into a few succint commands. - -## Commands - -This is a non-exhaustive list of available Fidesctl CLI commands: - -* `fidesctl apply [--dry] [--diff]` - Creates or Updates resources found within the YAML file(s) at the specified path. -* `fidesctl evaluate [-k,--fides-key] [-m, --message] [--dry]` - Runs an evaluation of all policies, but a single policy can be specified using the `--fides-key` parameter. -* `fidesctl init-db` - Sets up the database by running all missing migrations. -* `fidesctl get ` - Looks up a specific resource on the server by its type and `fides_key`. -* `fidesctl ls ` - Shows a list of all resources of a certain type that exist on the server. -* `fidesctl ping` - Pings the API's healthcheck endpoint to make sure that it is reachable and ready for requests. -* `fidesctl reset-db` - Tears down the database, erasing all data. -* `fidesctl version` - Shows the version of Fides that is installed. -* `fidesctl view-config`- Show a JSON representation of the config that Fidesctl is using. diff --git a/docs/fides/docs/cli/apply.md b/docs/fides/docs/cli/apply.md new file mode 100644 index 0000000000..0c58b14816 --- /dev/null +++ b/docs/fides/docs/cli/apply.md @@ -0,0 +1,62 @@ +
+

apply

+ +
NAME
+ +
+ apply — create or update your resources +
+ +
SYNOPSIS
+ +
+ 
fidesctl apply manifest_dir [--dry] [--diff]
+
+ +
DESCRIPTION
+ +
+ The apply command reads the resource manifest files that are stored in manifest_dir and its subdirectories, and applies the resources to your server. If a named resource already exists, the resource is completely overwritten with the new description; if it doesn't exist, it's created. +

+ As it processes the manifests, the command announces how many resources it has created, updated, and deleted. +

+
+ +
ARGUMENTS
+ +
+
+ manifest_dir +
+
+ The root of a directory tree that contains the resource manifest files that you want to apply to the server. The directories in the tree may only contain valid YAML files that describe Fides resources. If you include any other file, the command will fail and the valid resource manifests will be ignored. +
+
+
OPTIONS
+ +
+
+ --diff +
+
+ In addition to printing the number of changed resources, the command prints a diff between the server's old and new states. The diff is in Python DeepDiff format. I'm guessing, here. +
+
+ +
+
+ --dry +
+
+ "Dry run" mode. As it applies the resource manifest files, apply prints out the number of resources it would create, update, and delete, but it doesn't actually apply the changes to your server. +
+
+
+
+ -h/--help +
+
+ Prints a synopsis of this command. +
+
+
diff --git a/docs/fides/docs/cli/cli.md b/docs/fides/docs/cli/cli.md new file mode 100644 index 0000000000..74c46cc111 --- /dev/null +++ b/docs/fides/docs/cli/cli.md @@ -0,0 +1,79 @@ +# fidesctl CLI Overview + +--- + +`fidesctl` provides an interactive shell that drives the Fides functionality. If you run Fides in a Docker container, you launch the `fidesctl` shell by `cd`ing to your `fides` root directory and running `make cli`. + +```bash +$ cd +$ make cli +``` + +When it's finished, `make cli` shows you a success message, `cd`s into the `fidesctl` directory, and presents you with the Docker prompt. Notice that the prompt includes your current working directory within the Docker container. + +```bash +⠿ Container fides-fidesctl-db-1 Running 0.0s //success message +root@f76b4a7af333:/fides/fidesctl# //prompt +``` + +You can then use the `fidesctl` command line interface commands. The commands are provided as arguments to the `fidesctl` program. For example, to run the `init-db` command, you do this: + +```bash +root@f76b4a7af333:/fides/fidesctl# fidesctl init-db +``` + +`fidesctl` itself takes a set of options. The most important option is `--config-path` which lets you supply a file that configures the `fidesctl` environment. +All `fidesctl` commands return 0 upon success. + + +
+
OPTIONS
+ +
+
+ -f/--config-path config_file +
+
+ Identifies a file that you can use to configure the fidesctl environment. For more information about the file, see fidesctl Configuration File. To see the current configuration file, do fidesctl view‑config. +
+
+
+
+ -v/--version +
+
+ Prints the fidesctl version number. +
+
+
+
+ -h/--help +
+
+ Prints a synopsis of the fidesctl command. All of the `fidesctl` commands, listed below, also support the -h/--help options. +
+
+ +
COMMANDS
+ +
+ + The fidesctl commands are listed below. Follow the links for more information. + +
    +
  • apply creates and updates resource objects by reading a set of resource manifest files.
    • +
  • delete deletes a resource.
    • +
  • evaluate runs your policies against your data and announces the results.
    • +
  • get prints information about a resource.
    • +
  • init-db initializes and launches your resource database.
    • +
  • ls lists the resources of a specific type.
    • +
  • parse validates the taxonomy built from a set of resource manifest files.
    • +
  • ping determines if the fides API host is ready to receive messages.
    • +
  • reset-db removes the previously-applied manifest data from your resource database.
    • +
  • view-config prints the fidesctl configuration settings as a JSON object.
    • +
  • webserver starts the fidesctl API server.
    • + +
+

+

+
diff --git a/docs/fides/docs/cli/configuration-file.md b/docs/fides/docs/cli/configuration-file.md new file mode 100644 index 0000000000..787b87ced4 --- /dev/null +++ b/docs/fides/docs/cli/configuration-file.md @@ -0,0 +1,3 @@ +# fidesctl Configuration File + +Under Construction"> The `fidesctl` configuration file will be documented here. \ No newline at end of file diff --git a/docs/fides/docs/cli/delete.md b/docs/fides/docs/cli/delete.md new file mode 100644 index 0000000000..1d2ac4cfc4 --- /dev/null +++ b/docs/fides/docs/cli/delete.md @@ -0,0 +1,61 @@ +
+

delete

+ +
NAME
+
+ delete — delete a resource +
+ +
SYNOPSIS
+
+ 
fidesctl delete resource_type fides_key
+
+ +
DESCRIPTION
+
+ The delete command deletes the resource object identified by the arguments. +
+ +
ARGUMENTS
+
+
+ resource_type +
+
+ The type of resource that you want to delete, one of the following: +
    +
  • data_category
    • +
  • data_qualifier
    • +
  • data_subject
    • +
  • data_use
    • +
  • dataset
    • +
  • organization
    • +
  • policy
    • +
  • registry
    • +
  • system
    • +
+
+
+
+
+ fides_key +
+
+
+ The fides key that uniquely identifies the resource that you want to delete. The key is given as the fides‑key property in the manifest file that defines the resource. To print the resource objects to the terminal, call fidesctl ls resource_type. +
+
+
+ +
OPTIONS
+
+
+ -h/--help +
+
+ Prints a synopsis of this command. +
+
+
+ + diff --git a/docs/fides/docs/cli/evaluate.md b/docs/fides/docs/cli/evaluate.md new file mode 100644 index 0000000000..d1110fe08c --- /dev/null +++ b/docs/fides/docs/cli/evaluate.md @@ -0,0 +1,68 @@ +
+

evaluate

+ +
NAME
+
+ evaluate — run your privacy policies against your data +
+ + SYNOPSIS +
+ 
fidesctl evaluate manifest_dir [-k/--fides-key key] [-m/--message message] [--dry]
+
+ +
DESCRIPTION
+ +
+ The evaluate command applies the resources defined in manifest_dir to your server (by calling apply), and then assesses your data's compliance to your policies. A failure means that you're trying to publish data that shouldn't be published; it's expected that you'll correct the data (or adjust the policy) before your next app deployment. +

If you want to evaluate a single policy, use the ‑‑fides‑key option, passing the fides key of the policy you wish to evaluate. +

+

+ Keep in mind that evaluate calls apply for you; you don't have to call it yourself before you call this command. +

+
+
ARGUMENTS
+ +
+
+ manifest_dir +
+
+ The root of a directory tree that contains the resource manifest files that you want to apply to the server. The directories in the tree may only contain valid YAML files that describe Fides resources. If you include any other file, the command will fail and the valid resources will be ignored. +
+
+
OPTIONS
+
+
+ -k/--fides-key key +
+
+ The fides key of the single policy that you wish to evaluate. The key is a string token that uniquely identifies the policy. A policy's fides key is given as the fides‑key property in the manifest file that defines the policy resource. To print the policy resources to the terminal, call fidesctl ls policy. +
+
+
+
+ -m/--message message +
+
+ A message that you can supply to describe the purpose of this evaluation. +
+
+
+
+ --dry +
+
+ "Dry run" mode. As it applies the resource manifest files, the command prints out the number of resources it would create, update, and delete, but it doesn't actually apply the changes to your server. +
+
+
+
+ -h/--help +
+
+ Prints a synopsis of this command. +
+
+
+ diff --git a/docs/fides/docs/cli/get.md b/docs/fides/docs/cli/get.md new file mode 100644 index 0000000000..305c2db51b --- /dev/null +++ b/docs/fides/docs/cli/get.md @@ -0,0 +1,64 @@ +
+ +

get

+ +
NAME
+ +
+ get — print information about a single resource +
+ +
SYNOPSIS
+ +
+ 
fidesctl get resource_type fides_key
+
+ +
DESCRIPTION
+ +
+ The get command prints a JSON object that describes the resource object identified by the arguments. +
+
ARGUMENTS
+
+
+ resource_type +
+
+ The type of resource that you want to retrieve, one of the following: +
    +
  • data_category
    • +
  • data_qualifier
    • +
  • data_subject
    • +
  • data_use
    • +
  • dataset
    • +
  • organization
    • +
  • policy
    • +
  • registry
    • +
  • system
    • +
+
+
+
+
+ fides_key +
+
+
+ The fides key that uniquely identifies the resource that you want to retrieve. The key is given as the fides‑key property in the manifest file that defines the resource. To print the resource objects to the terminal, call fidesctl ls resource_type. +
+
+
+ +
OPTIONS
+
+
+ -h/--help +
+
+ Prints a synopsis of this command. +
+
+
+ + diff --git a/docs/fides/docs/cli/init-db.md b/docs/fides/docs/cli/init-db.md new file mode 100644 index 0000000000..43752b4158 --- /dev/null +++ b/docs/fides/docs/cli/init-db.md @@ -0,0 +1,32 @@ +
+

init-db

+ +
NAME
+ +
+ init-db — initialize and launch your Fides policy database +
+ +
SYNOPSIS
+ +
+ 
fidesctl init-db
+
+ +
DESCRIPTION
+ +
+ The init-db command initializes and launches your Fides policy database. After you've initialized your database, you should add your policy resources by calling apply. +
+ + +
OPTIONS
+
+
+ -h/--help +
+
+ Prints a synopsis of this command. +
+
+
diff --git a/docs/fides/docs/cli/ls.md b/docs/fides/docs/cli/ls.md new file mode 100644 index 0000000000..88da712d81 --- /dev/null +++ b/docs/fides/docs/cli/ls.md @@ -0,0 +1,54 @@ +
+

ls

+ +
NAME
+ +
+ ls — print information about all the resources of a specific type +
+ +
SYNOPSIS
+ +
+ 
fidesctl ls resource_type
+
+ +
DESCRIPTION
+ +
+ The ls command prints a series of JSON objects that describe the resource_type resource objects that are defined by your system. +
+
ARGUMENTS
+
+
+ resource_type +
+
+ The type of resources that you want to retrieve, one of the following: +
    +
  • data_category
    • +
  • data_qualifier
    • +
  • data_subject
    • +
  • data_use
    • +
  • dataset
    • +
  • organization
    • +
  • policy
    • +
  • registry
    • +
  • system
    • +
+
+
+ + +
OPTIONS
+
+
+ -h/--help +
+
+ Prints a synopsis of this command. +
+
+
+ + diff --git a/docs/fides/docs/cli/parse.md b/docs/fides/docs/cli/parse.md new file mode 100644 index 0000000000..8b968752c5 --- /dev/null +++ b/docs/fides/docs/cli/parse.md @@ -0,0 +1,53 @@ +
+

parse

+ +
NAME
+ +
+ parse — validate a taxonomy +
+ +
SYNOPSIS
+ +
+ 
fidesctl parse manifest_dir [-v/--verbose]
+
+ +
DESCRIPTION
+ +
+ The parse command validates the taxonomy that's built from the resource manifest files that are stored in manifest_dir and its subdirectories. If the taxonomy is successfully validated, the command prints a success message and returns 0. If its invalid, the command prints one or more error messages and returns non-0. The taxonomy itself is displayed if you include the ‑‑verbose option, otherwise it's built silently. +

+ The resources that make up the taxonomy aren't applied to your server. +

+
+ +
ARGUMENTS
+ +
+
+ manifest_dir +
+
+ The root of a directory tree that contains the resource manifest files that will be used to build the taxonomy. +
+
+
OPTIONS
+ +
+
+ -v/--verbose +
+
+ Prints the taxonomy. +
+
+
+
+ -h/--help +
+
+ Prints a synopsis of this command. +
+
+
diff --git a/docs/fides/docs/cli/ping.md b/docs/fides/docs/cli/ping.md new file mode 100644 index 0000000000..61f9f16c50 --- /dev/null +++ b/docs/fides/docs/cli/ping.md @@ -0,0 +1,47 @@ +
+

ping

+ +
NAME
+ +
+ ping — query the health of the fides API host +
+ +
SYNOPSIS
+ +
+ 
fidesctl ping
+
+ +
DESCRIPTION
+ +
+ The ping command sends a message to the fides API healthcheck endpoint and prints the response. If the API host is up and running, you'll see this: + + ``` + $ fidesctl ping + Pinging http://fidesctl:8080/health... + { + "data": { + "message": "Fides service is healthy!" + } + } + ``` + + Any other response means the host isn't running or can't be reached. + +
+ +
OPTIONS
+
+
+ -h/--help +
+
+ Prints a synopsis of this command. +
+
+
+ + + diff --git a/docs/fides/docs/cli/reset-db.md b/docs/fides/docs/cli/reset-db.md new file mode 100644 index 0000000000..062af766de --- /dev/null +++ b/docs/fides/docs/cli/reset-db.md @@ -0,0 +1,40 @@ +
+

reset-db

+ +
NAME
+ +
+ reset-db — initialize and launch your Fides policy database +
+ +
SYNOPSIS
+ +
+ 
fidesctl reset-db [-y/--yes]
+
+ +
DESCRIPTION
+ +
+ The reset-db command removes the resources that you added through previous apply calls. The database is then re-initialized through init‑db. +
+ + +
OPTIONS
+
+
+ -y/--yes +
+
+ Before it removes the resources, reset-db prompts you to confirm the removal. The ‑y/‑‑yes option suppresses the prompt; resources are removed without your confirmation. +
+
+
+
+ -h/--help +
+
+ Prints a synopsis of this command. +
+
+
diff --git a/docs/fides/docs/cli/view-config.md b/docs/fides/docs/cli/view-config.md new file mode 100644 index 0000000000..c36a5b7154 --- /dev/null +++ b/docs/fides/docs/cli/view-config.md @@ -0,0 +1,34 @@ +
+

view-config

+ +
NAME
+ +
+ view-config — print your fidesctl configuration +
+ +
SYNOPSIS
+ +
+ 
fidesctl view-config
+
+ +
DESCRIPTION
+ +
+ The view-config command prints your fidesctl configuration. You can modify the configuration by passing a configuration file to fidesctl: + 
$ fidesctl --config-path config_file
+
+ + +
OPTIONS
+ +
+
+ -h/--help +
+
+ Prints a synopsis of this command. +
+
+
diff --git a/docs/fides/docs/cli/webserver.md b/docs/fides/docs/cli/webserver.md new file mode 100644 index 0000000000..a2b4a917e7 --- /dev/null +++ b/docs/fides/docs/cli/webserver.md @@ -0,0 +1,33 @@ +
+

webserver

+ +
NAME
+ +
+ webserver — start the fidesctl API server +
+ +
SYNOPSIS
+ +
+ 
fidesctl view-config
+
+ +
DESCRIPTION
+ +
+ The webserver command starts the `fidesctl` API server. +
+ + +
OPTIONS
+ +
+
+ -h/--help +
+
+ Prints a synopsis of this command. +
+
+
diff --git a/docs/fides/docs/css/fides.css b/docs/fides/docs/css/fides.css index 31b526288c..2628a061c8 100644 --- a/docs/fides/docs/css/fides.css +++ b/docs/fides/docs/css/fides.css @@ -1,81 +1,159 @@ +/* -- START: Default mode CSS -- */ +[data-md-color-scheme="default"] { + --md-typeset-color: rgb(79, 86, 107); + --md-default-fg-color--light: rgb(79, 86, 107); + --md-primary-fg-color: #0861CE; + --md-vis-bg-color: rgba(0, 0, 0, 0.02); + --md-code-bg-color: #0861ce27; + --md-code-fg-color: #0657b9; + --md-accent-fg-color: #1FDF8F; + --md-nav-border: #ccc; + --md-default-fg-color--lightest: rgb(137, 140, 147); + --md-code-hl-comment-color: rgb(193, 201, 210); + --md-code-hl-string-color:rgb(133, 217, 150); + --md-code-hl-keyword-color: rgb(245, 251, 255); + --md-code-hl-punctuation-color: rgb(245, 251, 255); + --md-bg-footer-color: #0861CE; + --md-bg-table-header: rgba(79, 86, 107, 0.05); + --svg-highlight-col: #0657b9; +} + + +/* -- START: Slate/Dark mode CSS -- */ + +[data-md-color-scheme="slate"] { + --md-typeset-color: rgb(247, 250, 252); + --md-default-fg-color--light: rgb(247, 250, 252); + --md-default-bg-color: #2A2F45; + --md-primary-fg-color: #1A1D2E; + --md-accent-fg-color: #1FDF8F; + --md-typeset-a-color: rgb(3, 97, 206); + --md-vis-bg-color: rgba(0, 0, 0, 0.12); + --md-nav-border: #61647b; + --md-default-fg-color--lightest: rgb(191, 191, 191); + --md-code-bg-color: #1a1d2ea7; + --md-code-fg-color: #a3abd8; + --md-bg-footer-color: #1A1D2E; + --md-bg-table-header: rgba(233, 235, 252, 0.06); + --svg-highlight-col: #1FDF8F; +} + + body { font-family: 'Source Sans Pro', sans-serif !important; } -.md-header { - background-color: #0861ce; -} - .md-header .md-logo img { - width: 100px; + width: 60px; height: auto; } +.md-header__title { + margin-left: 0; +} + +.md-main__inner { + margin-top: 0; +} + +.md-sidebar { + padding-top: 0; +} +.md-sidebar__inner { + padding-top: 3.2em; + padding-bottom: 3.2em; +} +.md-sidebar__scrollwrap { + border-right: solid 1px var(--md-nav-border) !important; +} + .md-content h1, .md-content h2 { font-weight: 600; - color: #111439; } .md-footer { - background-color: #303036; padding: 30px 50px; color: white; } -.md-header__topic { - display: none; + +.md-typeset__table{ + display: block; } -.md-sidebar.md-sidebar--secondary { - visibility: hidden; +.md-typeset table:not([class]){ + display: table; } +.md-typeset code { + font-size: 0.65rem; + padding: 2px 4px; + border-radius: 4px; -.md-button.md-button--secondary.md-button-github { - padding-left: 60px; - background: url('../img/sprites.png') no-repeat 5px 4px; - background-size: 35px; - transition: all 0.5s ease; } -.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 + +.md-typeset .custom-license code { + color: #fff !important; } -.md-button.md-button--secondary.md-button-slack { - padding-left: 60px; - background: url('../img/sprites.png') no-repeat 5px -93px; - background-size: 35px; - transition: all 0.5s ease; + +p code, li code { + color: var(--md-code-fg-color); } -.md-button.md-button--secondary.md-button-slack:hover { - padding-left: 60px; - background: rgb(64, 81, 181) url('../img/sprites.png') no-repeat 5px -141px; - background-size: 35px - + + +.md-footer { + background-color: var(--md-bg-footer-color); } -.md-button.md-button--secondary.md-button-discord { - padding-left: 60px; - background: url('../img/sprites.png') no-repeat 5px -185px; - background-size: 35px; - transition: all 0.5s ease; + +.md-footer-meta { + display: none } -.md-button.md-button--secondary.md-button-discord:hover { - padding-left: 60px; - background: rgb(64, 81, 181) url('../img/sprites.png') no-repeat 5px -225px; - background-size: 35px - + +.md-typeset__table thead { + background-color: var(--md-bg-table-header); } -.md-typeset__table{ - display: block; +.svg-illustration #path-lines rect, .svg-illustration #path-lines polyline{ + stroke: var(--svg-highlight-col); + fill:none; } -.md-typeset table:not([class]){ - display: table; +.svg-illustration #path-lines polygon { + fill: var(--svg-highlight-col); +} +.svg-illustration #text { + fill: var(--md-typeset-color); +} + +/* -- Code Snippet Windows -- */ + + +.highlighttable .linenos, .highlighttable .code, .highlighttable .code, .md-typeset .highlighttable code { + background-color: rgb(26, 29, 46); + padding-top: 10px; + padding-bottom: 10px; +} +.highlighttable .linenos { + border-radius: 5px 0 0 5px; +} + +.highlighttable .code { + border-radius: 0 5px 5px 0; +} + +.highlighttable .linenodiv pre { + color: rgb(105, 115, 134); + +} +.highlighttable .linenodiv { + box-shadow: none; + margin-top: 10px; + margin-bottom: 10px; } + + /* -- START: Taxonomy Visualization Explorer CSS -- */ /* Typography */ @@ -88,7 +166,7 @@ body { color: #313f4e; margin: 0 auto; } - + .vis h1 { font-weight: 700; font-size: 26px; @@ -273,4 +351,4 @@ body { font-weight: 700; } -/* -- END: Taxonomy Visualization Explorer CSS -- */ \ No newline at end of file +/* -- END: Taxonomy Visualization Explorer CSS -- */ diff --git a/docs/fides/docs/css/stylesheet.css b/docs/fides/docs/css/stylesheet.css new file mode 100644 index 0000000000..31b526288c --- /dev/null +++ b/docs/fides/docs/css/stylesheet.css @@ -0,0 +1,276 @@ +body { + font-family: 'Source Sans Pro', sans-serif !important; +} + +.md-header { + background-color: #0861ce; +} + +.md-header .md-logo img { + width: 100px; + height: auto; +} + +.md-content h1, +.md-content h2 { + font-weight: 600; + color: #111439; +} + +.md-footer { + background-color: #303036; + padding: 30px 50px; + color: white; +} + +.md-header__topic { + display: none; +} + +.md-sidebar.md-sidebar--secondary { + visibility: hidden; +} + +.md-button.md-button--secondary.md-button-github { + padding-left: 60px; + background: url('../img/sprites.png') no-repeat 5px 4px; + background-size: 35px; + transition: all 0.5s ease; +} +.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 +} +.md-button.md-button--secondary.md-button-slack { + padding-left: 60px; + background: url('../img/sprites.png') no-repeat 5px -93px; + background-size: 35px; + transition: all 0.5s ease; +} +.md-button.md-button--secondary.md-button-slack:hover { + 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; + background: url('../img/sprites.png') no-repeat 5px -185px; + background-size: 35px; + transition: all 0.5s ease; +} +.md-button.md-button--secondary.md-button-discord:hover { + padding-left: 60px; + background: rgb(64, 81, 181) url('../img/sprites.png') no-repeat 5px -225px; + background-size: 35px + +} + +.md-typeset__table{ + display: block; +} + +.md-typeset table:not([class]){ + display: table; +} + + +/* -- START: Taxonomy Visualization Explorer CSS -- */ + +/* Typography */ +.vis { + font-family: "Source Sans Pro", sans-serif; + font-weight: 400; + font-size: 12px; + line-height: 1.5; + letter-spacing: 0.15px; + color: #313f4e; + margin: 0 auto; + } + +.vis h1 { + font-weight: 700; + font-size: 26px; + letter-spacing: -0.48px; + color: #111439; + margin: 0; +} + +.vis .legend { + font-weight: 600; + font-size: 10px; + letter-spacing: -0.19px; + color: #0a2540; +} + +.vis .card-title { + font-weight: 700; +} + +.vis .card-subtitle { + font-weight: 600; +} + +/* General */ +.vis-container { + max-width: 1400px; + text-align: center; +} + +.vis-container > * + * { + margin-top: 1.5rem; +} + +.chart-container > svg { + display: block; +} + +@media screen and (min-width: 1200px) { + .controls-container { + display: flex; + flex-wrap: wrap; + justify-content: space-between; + } +} + +.btn-group { + display: inline-flex; + vertical-align: middle; + margin: 0.25em; +} + +.btn { + line-height: 1; + font-size: 14px; + background-color: #eef2f7; + border: none; + padding: 0.65em 0.75em; + margin: 0; +} + +.btn--icon { + padding: 0; + width: 48px; + height: 2.3em; + display: inline-flexbox; + justify-content: center; + align-items: center; +} + +.btn:first-child { + border-top-left-radius: 2px; + border-bottom-left-radius: 2px; +} + +.btn:last-child { + border-top-right-radius: 2px; + border-bottom-right-radius: 2px; +} + +.btn:hover { + background-color: #e9ebee; +} + +.btn:active, +.btn.is-selected { + background-color: #cbd7e7; +} + +/* Legend */ +.vis-color-legend { + display: inline-flex; + justify-content: center; + flex-wrap: wrap; +} + +.vis-color-legend .legend-item { + display: inline-flex; + align-items: center; + margin-left: 0.5em; + margin-right: 0.5em; +} + +.vis-color-legend .legend-swatch { + width: 1em; + height: 1em; + margin-right: 0.5em; +} + +/* Tooltip */ +.vis-tooltip { + position: absolute; + top: 0; + left: 0; + background-color: #ffffff; + padding: 1em; + border-radius: 4px; + box-shadow: 0 2px 24px 0 rgba(0, 0, 0, 0.2); + pointer-events: none; + opacity: 0; + transition: opacity 0.15s; +} + +.vis-tooltip.is-visible { + opacity: 1; +} + +.vis-tooltip .card { + max-width: 240px; +} + +.vis-tooltip .card > * + * { + margin-top: 1em; +} + +/* Sunburst */ +.vis .sunburst-svg .partition-path, +.vis .sunburst-svg .label-text { + transition: fill 0.15s; +} + +.vis .sunburst-svg .partition-path.is-highlighted { + fill: #57f2ea; +} + +.vis .sunburst-svg .label-text.is-highlighted { + fill: currentColor; +} + +/* Radial Tree */ +/* Tree */ +.vis .radial-tree-svg .link, +.vis .radial-tree-svg .node, +.vis .tree-svg .link, +.vis .tree-svg .node { + transition: fill 0.15s; +} + +.vis .radial-tree-svg .link, +.vis .tree-svg .link { + stroke-width: 1.5px; +} + +.vis .radial-tree-svg .link.is-highlighted, +.vis .tree-svg .link.is-highlighted { + stroke: #57f2ea; + stroke-width: 2.5px; +} + +.vis .radial-tree-svg .node.is-highlighted, +.vis .tree-svg .node.is-highlighted { + fill: #57f2ea; +} + +.vis .radial-tree-svg .label-text .label-text__bg, +.vis .tree-svg .label-text .label-text__bg { + stroke: #ffffff; + stroke-width: 3px; +} + +.vis .radial-tree-svg .label-text.is-highlighted, +.vis .tree-svg .label-text.is-highlighted { + font-weight: 700; +} + +/* -- END: Taxonomy Visualization Explorer CSS -- */ \ No newline at end of file diff --git a/docs/fides/docs/css/swagger_override.css b/docs/fides/docs/css/swagger_override.css new file mode 100644 index 0000000000..eb57082b9f --- /dev/null +++ b/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; +} \ No newline at end of file diff --git a/docs/fides/docs/img/fides-logo.svg b/docs/fides/docs/img/fides-logo.svg index 0fde273e5d..20ac8dd588 100644 --- a/docs/fides/docs/img/fides-logo.svg +++ b/docs/fides/docs/img/fides-logo.svg @@ -1,29 +1,15 @@ - - - - - - - - - - - - + + + logo@2x + + + diff --git a/docs/fides/docs/js/vis.js b/docs/fides/docs/js/vis.js index 3de194e3d7..5743d08332 100644 --- a/docs/fides/docs/js/vis.js +++ b/docs/fides/docs/js/vis.js @@ -1,3 +1,5 @@ + + var VisColorLegend = class VisColorLegend { constructor({ el }) { this.el = el; diff --git a/docs/fides/mkdocs.yml b/docs/fides/mkdocs.yml index 6b944fdd24..24b1e9b5bb 100644 --- a/docs/fides/mkdocs.yml +++ b/docs/fides/mkdocs.yml @@ -29,7 +29,20 @@ nav: - Data Uses: language/taxonomy/data_uses.md - Data Subjects: language/taxonomy/data_subjects.md - Data Qualifiers: language/taxonomy/data_qualifiers.md - - CLI: cli.md + - CLI: + - CLI Overview: cli/cli.md + - Configuration File: cli/configuration-file + - apply: cli/apply.md + - delete: cli/delete.md + - evaluate: cli/evaluate.md + - get: cli/get.md + - init-db: cli/init-db.md + - ls: cli/ls.md + - parse: cli/parse.md + - ping: cli/ping.md + - reset-db: cli/reset-db.md + - view-config: cli/view-config.md + - webserver: cli/webserver.md - APIs: api/index.md - Development: - Overview: development/overview.md @@ -81,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 diff --git a/docs/md b/docs/md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/fidesctl/demo_resources/demo_dataset.yml b/fidesctl/demo_resources/demo_dataset.yml index 5d1c4e1bc2..563d25e328 100644 --- a/fidesctl/demo_resources/demo_dataset.yml +++ b/fidesctl/demo_resources/demo_dataset.yml @@ -30,3 +30,5 @@ dataset: description: User's unique ID data_categories: - user.derived.identifiable.unique_id + + diff --git a/fidesctl/src/fidesctl/cli/cli.py b/fidesctl/src/fidesctl/cli/cli.py index b19fa306ad..fcda66a8c1 100644 --- a/fidesctl/src/fidesctl/cli/cli.py +++ b/fidesctl/src/fidesctl/cli/cli.py @@ -33,12 +33,14 @@ @click.option( "--diff", is_flag=True, - help="Outputs a detailed diff of the local resource files compared to the server resources.", + help="Print the diff between the server's old and new states in Python DeepDiff format", ) @manifests_dir_argument def apply(ctx: click.Context, dry: bool, diff: bool, manifests_dir: str) -> None: """ - Send the manifest files to the server. + Update server with your local resources + \b. Reads the resource manifest files that are stored in MANIFESTS_DIR (and its subdirectories) and applies the resources to your server. If a named resource already exists, the resource is completely overwritten with the new description; if it doesn't exist, it's created. + """ config = ctx.obj["CONFIG"] taxonomy = _parse.parse(manifests_dir) @@ -57,7 +59,13 @@ def apply(ctx: click.Context, dry: bool, diff: bool, manifests_dir: str) -> None @fides_key_argument def delete(ctx: click.Context, resource_type: str, fides_key: str) -> None: """ - Delete an resource by its id. + Delete a specified resource + + \b. Args: + + [resource type list] (string): the type of resource from the enumeration that you want to delete + + FIDES_KEY (string): the Fides key of the resource that you want to delete. """ config = ctx.obj["CONFIG"] handle_cli_response( @@ -77,10 +85,12 @@ def delete(ctx: click.Context, resource_type: str, fides_key: str) -> None: "-k", "--fides-key", default="", - help="The fides_key for the specific Policy to be evaluated.", + help="The Fides key of the single policy that you wish to evaluate. This key is a string token that uniquely identifies the policy.", ) @click.option( - "-m", "--message", help="Description of the changes this evaluation encapsulates." + "-m", + "--message", + help="A message that you can supply to describe the purpose of this evaluation.", ) @dry_flag def evaluate( @@ -91,12 +101,9 @@ def evaluate( dry: bool, ) -> None: """ - Evaluate a registry or system, either approving or denying - based on organizational policies. + Assess your data's compliance to policies + \b. This command will first `apply` the resources defined in MANIFESTS_DIR to your server and then assess your data's compliance to your policies or single policy. - Evaluate will always run the "apply" command before the - evaluation, either dry or not depending on the flag - passed to "evaluate". """ config = ctx.obj["CONFIG"] @@ -126,13 +133,14 @@ def generate_dataset( ctx: click.Context, connection_string: str, output_filename: str ) -> None: """ - Generates a comprehensive dataset manifest from a database. + Connect a database to create a dataset + \b. Automatically create a dataset .yml file by directly connecting your database. Args: - connection_string (str): A SQLAlchemy-compatible connection string + connection_string (string): A SQLAlchemy-compatible connection string - output_filename (str): A path to where the manifest will be written + output_filename (string): A path to where the manifest will be written """ _generate_dataset.generate_dataset(connection_string, output_filename) @@ -144,7 +152,13 @@ def generate_dataset( @fides_key_argument def get(ctx: click.Context, resource_type: str, fides_key: str) -> None: """ - Get an resource by its id. + Print the resource as a JSON object + + \b\b. Args: + + [resource type list] (string): the type of resource from the enumeration that you want to retrieve + + FIDES_KEY (string): the Fides key of the resource that you want to retrieve """ config = ctx.obj["CONFIG"] handle_cli_response( @@ -161,7 +175,9 @@ def get(ctx: click.Context, resource_type: str, fides_key: str) -> None: @click.pass_context def init_db(ctx: click.Context) -> None: """ - Initialize or upgrade the database by running all of the existing migrations. + Initialize and launch your Fides policy database + \b. After you've initialized your database, you should add your policy resources by calling 'apply'. + """ config = ctx.obj["CONFIG"] database.init_db(config.api.database_url, fidesctl_config=config) @@ -172,7 +188,12 @@ def init_db(ctx: click.Context) -> None: @resource_type_argument def ls(ctx: click.Context, resource_type: str) -> None: # pylint: disable=invalid-name """ - List all resources of a certain type. + List resource objects + \b. This command will print the JSON object for the specified resource. + + Args: + + [resource type list] (string): the type of resource from the enumeration that you want to retrieve """ config = ctx.obj["CONFIG"] handle_cli_response( @@ -190,7 +211,10 @@ def ls(ctx: click.Context, resource_type: str) -> None: # pylint: disable=inval @verbose_flag def parse(ctx: click.Context, manifests_dir: str, verbose: bool = False) -> None: """ - Parse the file(s) at the provided path into a Taxonomy and surface any validation errors. + Validate the taxonomy described by the manifest files + \b. Reads the resource files that are stored in MANIFESTS_DIR and its subdirectories to verify presence of taxonomy valuse. If the taxonomy is successfully validated, the command prints a success message and returns 0. If invalid, the command prints one or more error messages and returns non-0. + + Note: No resources are applied to your server in this command. Enabling -v will print the taxonomy. """ taxonomy = _parse.parse(manifests_dir) @@ -202,7 +226,8 @@ def parse(ctx: click.Context, manifests_dir: str, verbose: bool = False) -> None @click.pass_context def ping(ctx: click.Context, config_path: str = "") -> None: """ - Ping the Server. + Confirm fidesctl is running + \b. Sends a message to the Fides API health-check endpoint and prints the response. """ config = ctx.obj["CONFIG"] healthcheck_url = config.cli.server_url + "/health" @@ -215,8 +240,9 @@ def ping(ctx: click.Context, config_path: str = "") -> None: @yes_flag def reset_db(ctx: click.Context, yes: bool) -> None: """ - Drops all tables and metadata from the database and - re-initializes the database. + Full database cleanse + \b. Removes the resources that you added through previous 'apply' calls, and then re-initializes the database by running `init-db`. + """ config = ctx.obj["CONFIG"] database_url = config.api.database_url @@ -238,7 +264,9 @@ def reset_db(ctx: click.Context, yes: bool) -> None: @click.pass_context def view_config(ctx: click.Context) -> None: """ - Print out the config values. + Prints the current fidesctl configuration. You can modify the configuration by passing a configuration file to the 'fidesctl' command: + + $ fidesctl --config-path config_files """ config = ctx.obj["CONFIG"] pretty_echo(config.dict(), color="green") @@ -248,6 +276,6 @@ def view_config(ctx: click.Context) -> None: @click.pass_context def webserver(ctx: click.Context) -> None: """ - Starts the API webserver. + Starts the fidesctl API server. """ start_webserver() diff --git a/fidesctl/src/fidesctl/cli/options.py b/fidesctl/src/fidesctl/cli/options.py index 0886a75917..97e97f4750 100644 --- a/fidesctl/src/fidesctl/cli/options.py +++ b/fidesctl/src/fidesctl/cli/options.py @@ -40,7 +40,7 @@ def dry_flag(command: Callable) -> Callable: command = click.option( "--dry", is_flag=True, - help="Runs the command without any side-effects.", + help="Dry run mode: this only prints the resources the command would normally create, update, and delete, without sending the changes to the server", )(command) return command @@ -51,17 +51,17 @@ def yes_flag(command: Callable) -> Callable: "--yes", "-y", is_flag=True, - help="Automatic yes to prompts.", + help="Automatically responds 'yes' to any prompts.", )(command) return command def verbose_flag(command: Callable) -> Callable: - "Add a flag that makes commands verbose." + "Turns on verbose output." command = click.option( "--verbose", "-v", is_flag=True, - help="Verbose output.", + help="Enable verbose output.", )(command) return command diff --git a/x b/x new file mode 100644 index 0000000000..3dfc00987e --- /dev/null +++ b/x @@ -0,0 +1,311 @@ +man(1) man(1) + + + +NNAAMMEE + man - format and display the on-line manual pages + +SSYYNNOOPPSSIISS + mmaann [--aaccddffFFhhkkKKttwwWW] [----ppaatthh] [--mm _s_y_s_t_e_m] [--pp _s_t_r_i_n_g] [--CC _c_o_n_f_i_g___f_i_l_e] + [--MM _p_a_t_h_l_i_s_t] [--PP _p_a_g_e_r] [--BB _b_r_o_w_s_e_r] [--HH _h_t_m_l_p_a_g_e_r] [--SS _s_e_c_t_i_o_n___l_i_s_t] + [_s_e_c_t_i_o_n] _n_a_m_e _._._. + + +DDEESSCCRRIIPPTTIIOONN + mmaann formats and displays the on-line manual pages. If you specify _s_e_c_- + _t_i_o_n, mmaann only looks in that section of the manual. _n_a_m_e is normally + the name of the manual page, which is typically the name of a command, + function, or file. However, if _n_a_m_e contains a slash (//) then mmaann + interprets it as a file specification, so that you can do mmaann ..//ffoooo..55 + or even mmaann //ccdd//ffoooo//bbaarr..11..ggzz. + + See below for a description of where mmaann looks for the manual page + files. + + +MMAANNUUAALL SSEECCTTIIOONNSS + The standard sections of the manual include: + + 11 User Commands + + 22 System Calls + + 33 C Library Functions + + 44 Devices and Special Files + + 55 File Formats and Conventions + + 66 Games et. Al. + + 77 Miscellanea + + 88 System Administration tools and Deamons + + Distributions customize the manual section to their specifics, which + often include additional sections. + + +OOPPTTIIOONNSS + --CC ccoonnffiigg__ffiillee + Specify the configuration file to use; the default is //pprrii-- + vvaattee//eettcc//mmaann..ccoonnff. (See mmaann..ccoonnff(5).) + + --MM ppaatthh + Specify the list of directories to search for man pages. Sepa- + rate the directories with colons. An empty list is the same as + not specifying --MM at all. See SSEEAARRCCHH PPAATTHH FFOORR MMAANNUUAALL PPAAGGEESS. + + --PP ppaaggeerr + Specify which pager to use. This option overrides the MMAANNPPAAGGEERR + environment variable, which in turn overrides the PPAAGGEERR vari- + able. By default, mmaann uses //uussrr//bbiinn//lleessss --iiss. + + --BB Specify which browser to use on HTML files. This option over- + rides the BBRROOWWSSEERR environment variable. By default, mmaann uses + //uussrr//bbiinn//lleessss-is,, + + --HH Specify a command that renders HTML files as text. This option + overrides the HHTTMMLLPPAAGGEERR environment variable. By default, mmaann + uses //bbiinn//ccaatt, + + --SS sseeccttiioonn__lliisstt + List is a colon separated list of manual sections to search. + This option overrides the MMAANNSSEECCTT environment variable. + + --aa By default, mmaann will exit after displaying the first manual page + it finds. Using this option forces mmaann to display all the man- + ual pages that match nnaammee,, not just the first. + + --cc Reformat the source man page, even when an up-to-date cat page + exists. This can be meaningful if the cat page was formatted + for a screen with a different number of columns, or if the pre- + formatted page is corrupted. + + --dd Don't actually display the man pages, but do print gobs of + debugging information. + + --DD Both display and print debugging info. + + --ff Equivalent to wwhhaattiiss. + + --FF or ----pprreeffoorrmmaatt + Format only - do not display. + + --hh Print a help message and exit. + + --kk Equivalent to aapprrooppooss. + + --KK Search for the specified string in *all* man pages. Warning: + this is probably very slow! It helps to specify a section. + (Just to give a rough idea, on my machine this takes about a + minute per 500 man pages.) + + --mm ssyysstteemm + Specify an alternate set of man pages to search based on the + system name given. + + --pp ssttrriinngg + Specify the sequence of preprocessors to run before nnrrooffff or + ttrrooffff. Not all installations will have a full set of preproces- + sors. Some of the preprocessors and the letters used to desig- + nate them are: eqn (e), grap (g), pic (p), tbl (t), vgrind (v), + refer (r). This option overrides the MMAANNRROOFFFFSSEEQQ environment + variable. + + --tt Use //uussrr//bbiinn//ggrrooffff --TTppss --mmaannddoocc --cc to format the manual page, + passing the output to ssttddoouutt.. The default output format of + //uussrr//bbiinn//ggrrooffff --TTppss --mmaannddoocc --cc is Postscript, refer to the man- + ual page of //uussrr//bbiinn//ggrrooffff --TTppss --mmaannddoocc --cc for ways to pick an + alternate format. + + Depending on the selected format and the availability of printing + devices, the output may need to be passed through some filter or + another before being printed. + + --ww or ----ppaatthh + Don't actually display the man pages, but do print the loca- + tion(s) of the files that would be formatted or displayed. If no + argument is given: display (on stdout) the list of directories + that is searched by mmaann for man pages. If mmaannppaatthh is a link to + man, then "manpath" is equivalent to "man --path". + + --WW Like -w, but print file names one per line, without additional + information. This is useful in shell commands like mmaann --aaWW mmaann + || xxaarrggss llss --ll + + +CCAATT PPAAGGEESS + Man will try to save the formatted man pages, in order to save format- + ting time the next time these pages are needed. Traditionally, format- + ted versions of pages in DIR/manX are saved in DIR/catX, but other map- + pings from man dir to cat dir can be specified in //pprrii-- + vvaattee//eettcc//mmaann..ccoonnff. No cat pages are saved when the required cat direc- + tory does not exist. No cat pages are saved when they are formatted + for a line length different from 80. No cat pages are saved when + man.conf contains the line NOCACHE. + + It is possible to make mmaann suid to a user man. Then, if a cat directory + has owner man and mode 0755 (only writable by man), and the cat files + have owner man and mode 0644 or 0444 (only writable by man, or not + writable at all), no ordinary user can change the cat pages or put + other files in the cat directory. If mmaann is not made suid, then a cat + directory should have mode 0777 if all users should be able to leave + cat pages there. + + The option --cc forces reformatting a page, even if a recent cat page + exists. + + +HHTTMMLL PPAAGGEESS + Man will find HTML pages if they live in directories named as expected + to be ".html", thus a valid name for an HTML version of the llss(1) man + page would be _/_u_s_r_/_s_h_a_r_e_/_m_a_n_/_h_t_m_l_m_a_n_1_/_l_s_._1_._h_t_m_l. + + +SSEEAARRCCHH PPAATTHH FFOORR MMAANNUUAALL PPAAGGEESS + mmaann uses a sophisticated method of finding manual page files, based on + the invocation options and environment variables, the //pprrii-- + vvaattee//eettcc//mmaann..ccoonnff configuration file, and some built in conventions and + heuristics. + + First of all, when the _n_a_m_e argument to mmaann contains a slash (//), mmaann + assumes it is a file specification itself, and there is no searching + involved. + + But in the normal case where _n_a_m_e doesn't contain a slash, mmaann searches + a variety of directories for a file that could be a manual page for the + topic named. + + If you specify the --MM _p_a_t_h_l_i_s_t option, _p_a_t_h_l_i_s_t is a colon-separated + list of the directories that mmaann searches. + + If you don't specify --MM but set the MMAANNPPAATTHH environment variable, the + value of that variable is the list of the directories that mmaann + searches. + + If you don't specify an explicit path list with --MM or MMAANNPPAATTHH, mmaann + develops its own path list based on the contents of the configuration + file //pprriivvaattee//eettcc//mmaann..ccoonnff. The MMAANNPPAATTHH statements in the configura- + tion file identify particular directories to include in the search + path. + + Furthermore, the MMAANNPPAATTHH__MMAAPP statements add to the search path depend- + ing on your command search path (i.e. your PPAATTHH environment variable). + For each directory that may be in the command search path, a MMAANN-- + PPAATTHH__MMAAPP statement specifies a directory that should be added to the + search path for manual page files. mmaann looks at the PPAATTHH variable and + adds the corresponding directories to the manual page file search path. + Thus, with the proper use of MMAANNPPAATTHH__MMAAPP, when you issue the command + mmaann xxyyzz, you get a manual page for the program that would run if you + issued the command xxyyzz. + + In addition, for each directory in the command search path (we'll call + it a "command directory") for which you do _n_o_t have a MMAANNPPAATTHH__MMAAPP + statement, mmaann automatically looks for a manual page directory "nearby" + namely as a subdirectory in the command directory itself or in the par- + ent directory of the command directory. + + You can disable the automatic "nearby" searches by including a NNOOAAUU-- + TTOOPPAATTHH statement in //pprriivvaattee//eettcc//mmaann..ccoonnff. + + In each directory in the search path as described above, mmaann searches + for a file named _t_o_p_i_c.._s_e_c_t_i_o_n, with an optional suffix on the section + number and possibly a compression suffix. If it doesn't find such a + file, it then looks in any subdirectories named mmaann_N or ccaatt_N where _N is + the manual section number. If the file is in a ccaatt_N subdirectory, mmaann + assumes it is a formatted manual page file (cat page). Otherwise, mmaann + assumes it is unformatted. In either case, if the filename has a known + compression suffix (like ..ggzz), mmaann assumes it is gzipped. + + If you want to see where (or if) mmaann would find the manual page for a + particular topic, use the ----ppaatthh (--ww) option. + + +EENNVVIIRROONNMMEENNTT + MMAANNPPAATTHH + If MMAANNPPAATTHH is set, mmaann uses it as the path to search for manual + page files. It overrides the configuration file and the auto- + matic search path, but is overridden by the --MM invocation + option. See SSEEAARRCCHH PPAATTHH FFOORR MMAANNUUAALL PPAAGGEESS. + + MMAANNPPLL If MMAANNPPLL is set, its value is used as the display page length. + Otherwise, the entire man page will occupy one (long) page. + + MMAANNRROOFFFFSSEEQQ + If MMAANNRROOFFFFSSEEQQ is set, its value is used to determine the set of + preprocessors run before running nnrrooffff or ttrrooffff. By default, + pages are passed through the tbl preprocessor before nnrrooffff. + + MMAANNSSEECCTT + If MMAANNSSEECCTT is set, its value is used to determine which manual + sections to search. + + MMAANNWWIIDDTTHH + If MMAANNWWIIDDTTHH is set, its value is used as the width manpages + should be displayed. Otherwise the pages may be displayed over + the whole width of your screen. + + MMAANNPPAAGGEERR + If MMAANNPPAAGGEERR is set, its value is used as the name of the program + to use to display the man page. If not, then PPAAGGEERR is used. If + that has no value either, //uussrr//bbiinn//lleessss --iiss is used. + + BBRROOWWSSEERR + The name of a browser to use for displaying HTML manual pages. + If it is not set, /usr/bin/less -is is used. + + HHTTMMLLPPAAGGEERR + The command to use for rendering HTML manual pages as text. If + it is not set, /bin/cat is used. + + LLAANNGG If LLAANNGG is set, its value defines the name of the subdirectory + where man first looks for man pages. Thus, the command `LANG=dk + man 1 foo' will cause man to look for the foo man page in + .../dk/man1/foo.1, and if it cannot find such a file, then in + .../man1/foo.1, where ... is a directory on the search path. + + NNLLSSPPAATTHH,, LLCC__MMEESSSSAAGGEESS,, LLAANNGG + The environment variables NNLLSSPPAATTHH and LLCC__MMEESSSSAAGGEESS (or LLAANNGG when + the latter does not exist) play a role in locating the message + catalog. (But the English messages are compiled in, and for + English no catalog is required.) Note that programs like ccooll((11)) + called by man also use e.g. LC_CTYPE. + + PPAATTHH PPAATTHH helps determine the search path for manual page files. See + SSEEAARRCCHH PPAATTHH FFOORR MMAANNUUAALL PPAAGGEESS. + + SSYYSSTTEEMM SSYYSSTTEEMM is used to get the default alternate system name (for use + with the --mm option). + +BBUUGGSS + The --tt option only works if a troff-like program is installed. + If you see blinking \255 or instead of hyphens, put `LESS- + CHARSET=latin1' in your environment. + +TTIIPPSS + If you add the line + + (global-set-key [(f1)] (lambda () (interactive) (manual-entry (cur- + rent-word)))) + + to your _._e_m_a_c_s file, then hitting F1 will give you the man page for the + library call at the current cursor position. + + To get a plain text version of a man page, without backspaces and + underscores, try + + # man foo | col -b > foo.mantxt + +AAUUTTHHOORR + John W. Eaton was the original author of mmaann. Zeyd M. Ben-Halim + released man 1.2, and Andries Brouwer followed up with versions 1.3 + thru 1.5p. Federico Lucifredi is the current + maintainer. + +SSEEEE AALLSSOO + apropos(1), whatis(1), less(1), groff(1), man.conf(5). + + + + September 19, 2005 man(1)