openapi: 3.0.3 info: description: 'The HuBMAP User Key/Value API is a RESTful web service with create/update, read, and delete operations for key/value pairs associated with an authorized user, which persist in a backend data store.' version: 1.0.1 title: HuBMAP UKV API contact: name: HuBMAP Help Desk email: help@hubmapconsortium.org license: name: MIT License url: 'https://github.com/x-atlas-consortia/user-key-value-api/blob/main/LICENSE' servers: - url: 'https://ukv.api.hubmapconsortium.org/' security: - bearerAuth: [] components: securitySchemes: bearerAuth: type: apiKey name: Authorization in: header description: Globus bearer token to authorize requests to pass AWS API Gateway import validation. Prefixed with "Bearer "--e.g., "Bearer " schemas: KeyValuePair: type: object properties: key: type: string description: "The key used to retrieve the associated value for a user. A string of 50 or less allowed UTF-8 characters. Disallowed characters are whitespace, \", ', `, #, _, and %." value: type: string description: "Valid JSON for a non-empty object or array." KeyValueObject: type: object properties: propertyName: type: string enum: [key, value] propertyValue: type: string description: "Either the name of the key or the JSON of the value, each described in #/components/schemas/KeyValuePair" KeyValueArray: type: array items: $ref: '#/components/schemas/KeyValueObject' KeyValueErrorMessage: type: object properties: error: type: string description: "Description of the number of #/components/schemas/KeyValuePair entries which caused an error" error_by_key: type: object description: "JSON object with an entry for each error of the #/components/schemas/KeyValueArray" properties: key: type: string description: "The key name specified in a #/components/schemas/KeyValuePair which caused an error" value: type: string description: "An error message describing the error in the associated #/components/schemas/KeyValuePair of the #/components/schemas/KeyValueArray" paths: '/user/keys/{key}': put: summary: Creates a single key/value pair for the user in the backend data store, or updates the value if the key already exists. The associated value is valid JSON for a non-empty object or array. The key/value pair will be associated with the Globus ID connected to the bearer token presented for authorization. parameters: - name: key in: path description: A string of 50 or less allowed UTF-8 characters. Disallowed characters are whitespace, ", ', `, \#, _, and %. required: true schema: type: string requestBody: description: Valid JSON for a non-empty object or array to be stored as the value associated with {key}. content: application/json: schema: oneOf: - type: object - type: array examples: exampleObject: value: {"my-best-item": "tools", "my-worst-item": "tasks"} exampleArray: value: ["tools", "tasks", "time"] responses: '200': description: The key was created or updated with the value of the JSON in the Request and the Globus ID of the bearer token. The Response has a JSON body with one object with a "message" key, and the associated value confirms the successful operation '400': description: The create or update operation failed, so nothing changed in the data store. The Response has a JSON body with one object with an "error" key, and the associated value describes the problem. Typical causes are keys which have whitespace or disallowed characters, keys which are too long, and invalid JSON in the Request. '401': description: The user provided Globus token has expired or the user did not supply a valid token. '403': description: The user provided Globus token does not have the desired membership permission to access this resource. '500': description: An internal error occurred, causing the operation to fail, so nothing changed in the data store. Typical of unexpected problems and monitored by IT staff. get: summary: Reads the value of a single key/value pair for the user in the backend data store. The value is the complete JSON body attached to the Response. The key/value pair will be associated with the Globus ID connected to the bearer token presented for authorization. parameters: - name: key in: path description: A string of 50 or less allowed UTF-8 characters. Disallowed characters are whitespace, ", ', `, \#, _, and %. required: true schema: type: string responses: '200': description: The key in the Request parameter was read for the Globus ID of the bearer token. The Response has a JSON body which is the complete value stored for the user's key '400': description: The read operation failed. The Response has a JSON body with one object with an "error" key, and the associated value describes the problem. Typical causes are keys which have whitespace or disallowed characters and keys which are too long. '401': description: The user provided Globus token has expired or the user did not supply a valid token. '403': description: The user provided Globus token does not have the desired membership permission to access this resource. '404': description: The read operation failed because the key was not found for the user. The Response has a JSON body with one object with an "error" key, and the associated value describes the problem. '500': description: An internal error occurred, causing the operation to fail, so nothing changed in the data store. Typical of unexpected problems and monitored by IT staff. delete: summary: Delete from the backend data store a single key/value pair associated with the Globus ID connected to the bearer token presented for authorization. parameters: - name: key in: path description: A string of 50 or less allowed UTF-8 characters. Disallowed characters are whitespace, ", ', `, \#, _, and %. required: true schema: type: string responses: '200': description: The key in the Request parameter and its value were deleted for the Globus ID of the bearer token. '400': description: The delete operation failed. The Response has a JSON body with one object with an "error" key, and the associated value describes the problem. Typical causes are keys which have whitespace or disallowed characters and keys which are too long. '401': description: The user provided Globus token has expired or the user did not supply a valid token. '403': description: The user provided Globus token does not have the desired membership permission to access this resource. '404': description: The delete operation failed because the key was not found for the user. The Response has a JSON body with one object with an "error" key, and the associated value describes the problem. '500': description: An internal error occurred, causing the operation to fail, so nothing changed in the data store. Typical of unexpected problems and monitored by IT staff. '/user/keys': put: summary: Using the JSON body of the Request, creates key/value pairs for the user in the backend data store, or updates the value of any key which already exists. The associated value of each key is valid JSON for a non-empty object or array. Each key/value pair will be associated with the Globus ID connected to the bearer token presented for authorization. requestBody: description: Valid JSON for a non-empty array of objects, each of which contains one key/value pair to be stored for the user. content: application/json: schema: oneOf: - $ref: '#/components/schemas/KeyValueArray' example: [{"key": "my-stashed-dict", "value": {"my-best-item": "tools", "my-worst-item": "tasks"}}, {"key": "my-stashed-list", "value": ["tools", "tasks", "time"]}] responses: '200': description: Every key/value pair was created or updated using the JSON array of the Request and the Globus ID of the bearer token. The Response has a JSON body with one object with a "message" key, and the associated value confirms the successful operation '400': description: Creation or update failed for one or more key/value pairs, so nothing changed in the data store. The Response has a JSON body with one object with an "error" key, and the associated value describes the problem. Typical causes are keys which have whitespace or disallowed characters, keys which are too long, and invalid JSON in the Request. '401': description: The user provided Globus token has expired or the user did not supply a valid token. '403': description: The user provided Globus token does not have the desired membership permission to access this resource. '500': description: An internal error occurred, causing the operation to fail, so nothing changed in the data store. Typical of unexpected problems and monitored by IT staff. get: summary: Reads all the key/value pairs for the user in the backend data store. The key/value pairs will be associated with the Globus ID connected to the bearer token presented for authorization. responses: '200': description: All key/value pairs were retrieved for the Globus ID of the bearer token. The Response has a JSON body which is an array of objects, one for each key/value pair content: application/json: schema: oneOf: - $ref: '#/components/schemas/KeyValueArray' example: [{"key": "my-stashed-dict", "value": {"my-best-item": "tools", "my-worst-item": "tasks"}}, {"key": "my-stashed-list", "value": ["tools", "tasks", "time"]}] '401': description: The user provided Globus token has expired or the user did not supply a valid token. '403': description: The user provided Globus token does not have the desired membership permission to access this resource. '404': description: No key/value pairs were found for the Globus ID of the bearer token in the data store. The Response has a JSON body with one object with an "error" key, and the associated value describes the problem. '500': description: An internal error occurred, causing the operation to fail. Typical of unexpected problems and monitored by IT staff. '/user/find/keys': post: summary: Reads the specified key/value pairs for the user in the backend data store. The keys to retrieve are specified in a JSON array attached to the request body. The key/value pairs will be associated with the Globus ID connected to the bearer token presented for authorization. The value is the complete JSON body attached to the Response. The key/value pair will be associated with the Globus ID connected to the bearer token presented for authorization. requestBody: description: Valid JSON for a non-empty array, containing strings for existing key names in the data store. content: application/json: schema: type: array items: type: string example: '["keyname1", "keyname10", "keyname100"]' responses: '200': description: Specified key/value pairs were all retrieved for the Globus ID of the bearer token. The Response has a JSON body which is an array of objects, one for each key/value pair content: application/json: schema: oneOf: - $ref: '#/components/schemas/KeyValueArray' example: [{"key": "keyname1", "value": ["flour","water","salt","yeast"]},{"key": "keyname10", "value": ["wheat", "sourdough"]},{"key": "keyname100", "value": ["oven", "dutch oven", "bowls"]}] '400': description: The read operation failed. The Response has a JSON body with one array. Each element of array is an object with an "error" key, and the associated value describes the problem. Typical causes are keys which have whitespace or disallowed characters, keys which are too long, and invalid JSON in the Request. Any key specified in the Request that does not have an error message was found in the data store but not returned in the error Response. '401': description: The user provided Globus token has expired or the user did not supply a valid token. '403': description: The user provided Globus token does not have the desired membership permission to access this resource. '404': description: The read operation failed because at least one specified key was not found for the user. The Response has a JSON body with one object with an "error" key, whose value describes the problem, and one "unfound_keys" key, whose value is an array of unfound keys specified. '500': description: An internal error occurred, causing the operation to fail, so nothing changed in the data store. Typical of unexpected problems and monitored by IT staff.