@w3-commons/js-build-resources 0.0.1-security → 1.0.4

package/settings-service/src/swagger.json

@@ -0,0 +1,732 @@
+{
+  "openapi": "3.0.0",
+  "info": {
+    "title": "settings-service",
+    "description": "Settings Service is responsible for capturing IBM employee's personal preference settings within w3 portfolio",
+    "version": "1.0.0"
+  },
+  "servers": [
+    {
+      "url": "/v1",
+      "description": "Default"
+    }
+  ],
+  "tags": [
+    {
+      "name": "User",
+      "description": "A user's preference settings"
+    },
+    {
+      "name": "App",
+      "description": "An app's preference settings"
+    },
+    {
+      "name": "Api Key",
+      "description": "Api key management"
+    }
+  ],
+  "paths": {
+    "/settings/apiKey/app/{appID}": {
+      "get": {
+        "description": "Endpoint to get existing api key for specified app. Must encode returned value with appID.",
+        "tags": [
+          "Api Key"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "in": "path",
+            "name": "appID",
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "description": "w3 project application id"
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/apiKey-getResponse"
+                 }
+              }
+            },
+            "description": "Successfully fetched the api key for the application"
+          },
+          "401": {
+            "description": "Missing required authentication header"
+          },
+          "403": {
+            "description": "You are not authorized for apiKey operations."
+          },
+          "400": {
+            "description": "Invalid appID"
+          }
+        }
+      },
+      "post": {
+        "description": "Endpoint to create api key for appId. Current key returned if already exists. Must encode returned value with appID.",
+        "tags": [
+          "Api Key"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "in": "path",
+            "name": "appID",
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "description": "w3 project application id"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "create api key successfully",
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "$ref": "#/components/schemas/apiKey-postAndPutResponse"
+                 }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing required authentication header"
+          },
+          "403": {
+            "description" : "You are not authorized for apiKey operations."
+          },
+          "400": {
+            "description": "Invalid appID"
+          }
+        }
+      },
+      "put": {
+        "description": "Endpoint to recreate existing api key for appId. Must encode returned value with appID.",
+        "tags": [
+          "Api Key"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "in": "path",
+            "name": "appID",
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "description": "w3 project application id"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "update api key successfully",
+            "content": {
+              "text/plain": {
+                "schema":  {
+                  "$ref": "#/components/schemas/apiKey-postAndPutResponse"
+                 }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing required authentication header"
+          },
+          "403": {
+            "description" : "You are not authorized for apiKey operations."
+          },
+          "400": {
+            "description": "Invalid appID"
+          }
+        }
+      }
+    },
+    "/settings/users/{userId}/apps/{appId}": {
+      "get": {
+        "description": "Endpoint to get a user's settings preferences",
+        "tags": [
+          "User"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          },
+          {
+            "ApiKeyAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "in": "path",
+            "name": "userId",
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "description": "IBM employee's serial number (CNUM)"
+          },
+          {
+            "in": "path",
+            "name": "appId",
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "description": "w3 project application id"
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "example": {
+                    "general": {
+                      "theme": "dark",
+                      "primaryLanguage": "en"
+                    }
+                  }
+                }
+              }
+            },
+            "description": "Successfully fetched this this user's settings preference on this given appId"
+          }
+        }
+      },
+      "post": {
+        "description": "Endpoint to initialize/update user's preferences",
+        "tags": [
+          "User"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "in": "path",
+            "name": "userId",
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "description": "IBM employee's serial number (CNUM)"
+          },
+          {
+            "in": "path",
+            "name": "appId",
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "description": "w3 project application id"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "example": {
+                  "theme": "dark",
+                  "primaryLanguage": "en"
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "update successfully",
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "object",
+                  "example": {
+                    "theme": "dark",
+                    "primaryLanguage": "en"
+                  }
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "You do not have valid bearer token to submit request"
+          }
+        }
+      }
+    },
+    "/settings/users/{userId}": {
+      "delete": {
+        "description": "Endpoint to delete all settings for a specific user. This endpoint is locked down to apps on the RESTRICTED_APP_ID_WHITELIST only",
+        "tags": [
+          "User"
+        ],
+        "security": [
+          {
+            "ApiKeyAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "in": "path",
+            "name": "userId",
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "description": "user CNUM"
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "string",
+                  "example":  "success"
+                }
+              }
+            },
+            "description": "Successfully deleted settings for this user"
+          },
+          "401": {
+            "description": "API key based authentication strategy must be used for delete settings operation. (apps on the RESTRICTED_APP_ID_WHITELIST only)"
+          }
+        }
+      }
+    },
+    "/settings/users/all": {
+      "get": {
+        "description": "Endpoint to fetch all user information in the database. This endpoint is locked down to apps on the RESTRICTED_APP_ID_WHITELIST only. ",
+        "tags": [
+          "User"
+        ],
+        "security": [
+          {
+            "ApiKeyAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "in": "query",
+            "name": "fetchSize",
+            "schema": {
+              "type": "string"
+            },
+            "required": false,
+            "description": "number of records to fetch per request limited to <1000"
+          },
+          {
+            "in": "query",
+            "name": "pageState",
+            "schema": {
+              "type": "string"
+            },
+            "required": false,
+            "description": "pageState value from the last request to fetch the next page"
+          },
+          {
+            "in": "query",
+            "name": "appId",
+            "schema": {
+              "type": "string"
+            },
+            "required": false,
+            "description": "limit returned records to specific appId"
+          },
+          {
+            "in": "query",
+            "name": "settingName",
+            "schema": {
+              "type": "string"
+            },
+            "required": false,
+            "description": "limit returned records to specific settingName, appId must also be provided to use this option"
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "example": {
+                    "settings": {
+                      "user_id": "TESTCNUM",
+                      "app_id": "TESTAPP",
+                      "setting_name": "TEST SETTING NAME",
+                      "setting_value": "TEST SETTING VALUE"
+                    },
+                    "pageState": "pageState string"
+                  }
+                }
+              }
+            },
+            "description": "Retrieve all user settings"
+          },
+          "401": {
+            "description": "API key based authentication strategy must be used for delete settings operation. (apps on RESTRICTED_APP_ID_WHITELIST only)"
+          }
+        }
+      }
+    },
+    "/settings/app/{appId}": {
+      "get": {
+        "description": "Endpoint to get all app's settings preferences",
+        "tags": [
+          "App"
+        ],
+        "security": [
+          {
+            "ApiKeyAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "in": "path",
+            "name": "appId",
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "description": "w3 project application id"
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "default": {
+                      "type": "string"
+                    },
+                    "options": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      }
+                    },
+                    "setting_type": {
+                      "type": "string"
+                    },
+                    "deprecated_values": {
+                      "type": "object",
+                      "properties": {
+                        "[key: string]": {
+                          "type": "string"
+                        }
+                      }
+                    }
+                  },
+                  "example": {
+                    "theme": {
+                      "default": "dark",
+                      "options": [
+                        "dark",
+                        "light"
+                      ],
+                      "setting_type": "string",
+                      "deprecated_values": {
+                        "oldValue": "newValue"
+                      }
+                    }
+                  }
+                }
+              }
+            },
+            "description": "Successfully fetched this this app's settings preference on this given appId"
+          },
+          "401": {
+            "description": "You do not have valid api token to submit request"
+          }
+        }
+      }
+    },
+    "/settings/app/{appId}/setting/{settingName}": {
+      "get": {
+        "description": "Endpoint to get an app's settings preference for this setting",
+        "tags": [
+          "App"
+        ],
+        "security": [
+          {
+            "ApiKeyAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "in": "path",
+            "name": "appId",
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "description": "w3 project application id"
+          },
+          {
+            "in": "path",
+            "name": "settingName",
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "description": "setting name"
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "default": {
+                      "type": "string"
+                    },
+                    "options": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      }
+                    },
+                    "setting_type" : {
+                      "type": "string"
+                    },
+                    "deprecated_values": {
+                      "type": "object",
+                      "properties": {
+                        "[key: string]": {
+                          "type": "string"
+                        }
+                      }
+                    }
+                  },
+                  "example": {
+                      "default": "dark",
+                      "options": [
+                        "dark",
+                        "light"
+                      ],
+                      "setting_type": null,
+                      "deprecated_values": {
+                        "oldValue": "newValue"
+                    }
+                  }
+                }
+              }
+            },
+            "description": "Successfully fetched this this app's settings preference on this given appId"
+          },
+          "401": {
+            "description": "You do not have valid api token to submit request"
+          }
+        }
+      },
+      "post": {
+        "description": "Endpoint to initialize/update app's preferences. We recommend you use the get request to get the current values and then modify the settings object from that response to build your request. Any changed values will overwrite the old values, any values not passed will overwrite the old values as null.",
+        "tags": [
+          "App"
+        ],
+        "security": [
+          {
+            "ApiKeyAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "in": "path",
+            "name": "appId",
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "description": "w3 project application id"
+          },
+          {
+            "in": "path",
+            "name": "settingName",
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "description": "setting name"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                  "type": "object",
+                  "properties": {
+                    "default": {
+                      "type": "string"
+                    },
+                    "options": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      }
+                    },
+                    "setting_type": {
+                      "type": "string",
+                    },
+                    "deprecated_values": {
+                      "type": "object",
+                      "properties": {
+                        "[key: string]": {
+                          "type": "string"
+                        }
+                      }
+                    }
+                  },
+                  "example": {
+                      "default": "dark",
+                      "options": [
+                        "dark",
+                        "light"
+                      ],
+                      "setting_type" : null,
+                      "deprecated_values": {
+                        "oldValue": "newValue"
+                      }
+                  }
+
+                }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "update successfully",
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string",
+                  "example": "Success"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "You do not have valid api token to submit request"
+          }
+        }
+      },
+      "delete": {
+        "description": "Endpoint to delete an app's settings preference for this setting",
+        "tags": [
+          "App"
+        ],
+        "security": [
+          {
+            "ApiKeyAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "in": "path",
+            "name": "appId",
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "description": "w3 project application id"
+          },
+          {
+            "in": "path",
+            "name": "settingName",
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "description": "setting name"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "update successfully",
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string",
+                  "example": "Success"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "You do not have valid api token to submit request"
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "apiKey-getResponse": {
+        "type": "object",
+        "properties": {
+          "appId": {
+             "type": "string"
+          },
+          "key": {
+             "type": "string"
+          }
+       },
+       "example": {
+        "appId": "test",
+        "key": "O7ZevqTkDZKFRA6z1Cry8UUKJ1Uzsca9oyRYvQl2WmYZrGOL"
+        }
+      },
+      "apiKey-postAndPutResponse": {
+        "type": "object",
+        "properties": {
+          "appId": {
+             "type": "string"
+          },
+          "key": {
+             "type": "string"
+          }
+       },
+       "example": {
+        "key": "O7ZevqTkDZKFRA6z1Cry8UUKJ1Uzsca9oyRYvQl2WmYZrGOL"
+        }
+      }
+    },
+    "securitySchemes": {
+      "bearerAuth": {
+        "type": "http",
+        "scheme": "bearer",
+        "bearerFormat": "JWT"
+      },
+      "ApiKeyAuth": {
+        "type": "apiKey",
+        "in": "header",
+        "name": "authorization"
+      }
+    }
+  }
+}