# Copyright 2020 The SODA Authors. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. # # SODA S3 API are updated for s3-compatibility, Some of the references are as follows: # # https://docs.aws.amazon.com/AmazonS3/latest/gsg/GetStartedWithS3.html # # New SODA s3 APIs are to be authenticated. The following explains request # authentication with the AWS Signature Version 4 algorithm. # # https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html # openapi: 3.0.0 servers: - description: SwaggerHub API Auto Mocking url: 'https://virtserver.swaggerhub.com/open83/multi-cloud/1.0.0' - url: 'http://virtserver.swaggerhub.com/opensds.io/OpenSDS-Multi-Cloud/1.0.0' info: description: | SODA Multi-cloud API to manage multi-cloud backend storages. You can find out more about Swagger at [https://sodafoundation.io/](https://sodafoundation.io/) version: 1.0.0 title: SODA Multi-Cloud API termsOfService: '://www.linuxfoundation.org/terms' contact: name: SODA Support url: 'https://opensds.slack.com' email: support@opensds.io license: name: Apache 2.0 url: 'http://www.apache.org/licenses/LICENSE-2.0.html' tags: - name: backend description: Muli-cloud cloud storage backends externalDocs: description: Find out more url: 'https://sodafoundation.io/' - name: types description: Supported storage backends externalDocs: description: Find out more url: 'https://sodafoundation.io/' - name: plan description: Migration plan externalDocs: description: Find out more url: 'https://sodafoundation.io/' - name: job description: Migration job externalDocs: description: Find out more url: 'https://sodafoundation.io/' - name: policy description: Schedule policy of plan. externalDocs: description: Find out more url: 'https://sodafoundation.io/' - name: s3 description: s3 interface of multi-cloud externalDocs: description: Find out more url: 'https://sodafoundation.io/' paths: '/{tenantId}/backends': parameters: - name: tenantId in: path description: The tenant UUID in a multi-tenancy environment. required: true schema: type: string post: tags: - backend summary: Create a backend. operationId: createBackend responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/Backend' '415': description: Unsupported Media Type '401': description: Unauthorized token not found in header requestBody: $ref: '#/components/requestBodies/Backend' get: tags: - backend summary: List all backends. operationId: listBackend parameters: - name: type in: query description: Filter the backend by backend type. schema: type: string enum: &CLOUD_BACKENDS - hw-obs - aws-s3 - azure-blob - ceph-s3 - gcp-s3 - fusionstorage-object - ibm-cos - yig example: *CLOUD_BACKENDS - name: name in: query description: Filter the backend by name. schema: type: string - name: region in: query description: Filter the backend by region. schema: type: string - $ref: '#/components/parameters/offset' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/sort' responses: '200': description: successful operation. content: application/json: schema: type: object properties: backends: type: array items: $ref: '#/components/schemas/Backend' next: type: integer example: 1 '401': description: Unauthorized token not found in header '/{tenantId}/backends/{backendId}': parameters: - name: tenantId in: path description: The tenantId UUID in a multi-tenancy environment. required: true schema: type: string - name: backendId in: path description: The backend ID. required: true schema: type: string get: tags: - backend summary: Get a backend information. operationId: getBackend responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/Backend' '401': description: Unauthorized token not found in header '404': description: The resource does not exist. put: tags: - backend summary: Update a backend. operationId: updateBackend responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/Backend' '401': description: Unauthorized token not found in header '404': description: The resource does not exist. requestBody: content: application/json: schema: type: object properties: Access: description: Updated the specified backend access Id type: string example: 'AMIKJGNJLHUEBWTNDL6X' Security: description: Updated the specified backend security Id type: string example: 'Fsgs5KHAcs12420yGHNDGne8x8i5naHvdf/xZbTH' delete: tags: - backend summary: Deletes a backend. operationId: deleteBackend responses: '200': description: Delete success '400': description: Invalid ID supplied '401': description: Unauthorized token not found in header '404': description: The resource does not exist. '500': description: The backend can not be deleted. please delete bucket first '/{tenantId}/types': parameters: - name: tenantId in: path description: The tenantId UUID in a multi-tenancy environment. required: true schema: type: string get: tags: - types summary: List all supported storage backend type. operationId: listBackendTypes parameters: - name: name in: query description: Filter the backend by name. schema: type: string - $ref: '#/components/parameters/offset' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/sort' responses: '200': description: successful operation. content: application/json: schema: type: object properties: backends: type: array items: $ref: '#/components/schemas/Type' next: type: integer example: 1 '401': description: Unauthorized token not found in header '/{tenantId}/plans': parameters: - name: tenantId in: path description: The tenant UUID in a multi-tenancy environment. required: true schema: type: string post: tags: - plan summary: Create a plan. operationId: createPlan responses: '200': description: successful operation content: application/json: schema: type: object properties: plan: $ref: '#/components/schemas/Plan' '400': description: Bad Request '401': description: Unauthorized requestBody: $ref: '#/components/requestBodies/Plan' get: tags: - plan summary: List all plans. operationId: listPlans parameters: - name: type in: query description: >- Filter the plans by plan type. Only migration support currently. New type will be added in the future. schema: type: string enum: - migration - name: name in: query description: Filter the plan by name. schema: type: string - $ref: '#/components/parameters/offset' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/sort' responses: '200': description: successful operation. content: application/json: schema: type: object properties: plans: type: array items: $ref: '#/components/schemas/Plan' next: type: integer example: 1 '401': description: Unauthorized token not found in header '/{tenantId}/plans/{planId}': parameters: - name: tenantId in: path description: The tenant UUID in a multi-tenancy environment. required: true schema: type: string - name: planId in: path description: The plan ID required: true schema: type: string get: tags: - plan summary: Get a plan. operationId: getPlan responses: '200': content: application/json: schema: type: object properties: plan: $ref: '#/components/schemas/Plan' description: successful operation. '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: The resource does not exist i.e. Plan does not exist. put: tags: - plan summary: Update a plan. operationId: updatePlan responses: '200': description: successful operation content: application/json: schema: type: object properties: plan: $ref: '#/components/schemas/Plan' '401': description: Unauthorized '404': description: The resource does not exist i.e. Plan does not exist. requestBody: $ref: '#/components/requestBodies/Plan' delete: tags: - plan summary: Delete a plan. operationId: deletePlan responses: '200': description: Delete success content: application/json: schema: type: object '401': description: Unauthorized '404': description: The resource does not exist i.e. Plan does not exist. post: tags: - plan summary: Run a plan. operationId: runPlan responses: '200': description: Run success content: application/json: schema: type: object properties: jobId: type: string description: Id of the Job created for the Plan example: '5eaa86fe6f384d000116d1d5' '401': description: Unauthorized '404': description: The resource does not exist i.e. Plan does not exist. '/{tenantId}/jobs': parameters: - name: tenantId in: path description: The tenant UUID in a multi-tenancy environment. required: true schema: type: string get: tags: - job summary: List all jobs. operationId: listJobs parameters: - name: type in: query description: >- Filter the jobs by job type. Only migration support currently. New type will be added in the future. schema: type: string enum: &JOBS - migration example: migration - $ref: '#/components/parameters/offset' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/sort' responses: '200': description: successful operation. content: application/json: schema: type: object properties: jobs: type: array items: $ref: '#/components/schemas/Job' next: type: integer example: 1 '401': description: Unauthorized token not found in header '/{tenantId}/jobs/{jobId}': parameters: - name: tenantId in: path description: The tenant UUID in a multi-tenancy environment. required: true schema: type: string - name: jobId in: path description: The job ID required: true schema: type: string get: tags: - job summary: Get a job. operationId: getJob responses: '200': content: application/json: schema: type: object properties: job: $ref: '#/components/schemas/Job' description: successful operation. '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: The resource does not exist. '/{tenantId}/policies': parameters: - name: tenantId in: path description: The tenant UUID in a multi-tenancy environment. required: true schema: type: string post: tags: - policy summary: Create a policy. operationId: createPolicy responses: '200': description: successful operation content: application/json: schema: type: object properties: policy: $ref: '#/components/schemas/Policy' '401': description: Unauthorized token not found in header requestBody: $ref: '#/components/requestBodies/Policy' get: tags: - policy summary: List all policies. operationId: listPolicies parameters: - $ref: '#/components/parameters/offset' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/sort' responses: '200': description: successful operation. content: application/json: schema: type: object properties: policies: type: array items: $ref: '#/components/schemas/Policy' next: type: integer example: 1 '401': description: Unauthorized token not found in header '/{tenantId}/policies/{policyId}': parameters: - name: tenantId in: path description: The tenant UUID in a multi-tenancy environment. required: true schema: type: string - name: policyId in: path description: The policy ID required: true schema: type: string get: tags: - policy summary: Get a policy. operationId: getPolicy responses: '200': content: application/json: schema: type: object properties: policy: $ref: '#/components/schemas/Policy' description: successful operation. '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: The resource does not exist. put: tags: - policy summary: Update a policy. operationId: updatePolicy responses: '200': description: successful operation content: application/json: schema: type: object properties: policy: $ref: '#/components/schemas/Policy' requestBody: $ref: '#/components/requestBodies/Policy' delete: tags: - policy summary: Delete a policy. operationId: deletePolicy responses: '200': description: Delete success content: application/json: schema: type: object '400': description: Invalid ID supplied '401': description: Unauthorized token not found in header '/': parameters: - name: bucketName in: path description: the name of bucket required: true schema: type: string get: tags: - s3 summary: List Buckets. operationId: listBuckets responses: '200': description: successful operation list of buckets content: application/xml: schema: $ref: '#/components/schemas/ListAllMyBucketsResult' '403': description: Forbidden; Access Denied, InvalidAccessKey, SignatureDoesNotMatch '/{bucketName}': parameters: - name: bucketName in: path description: The name of the bucket required: true schema: type: string put: tags: - s3 summary: Create a bucket. operationId: bucketPut responses: '200': description: successful create bucket content: application/xml: schema: $ref: '#/components/schemas/BaseResponse' '403': description: Forbidden; Access Denied, InvalidAccessKey, SignatureDoesNotMatch '500': description: GetBackend Failed requestBody: content: application/xml: schema: $ref: '#/components/schemas/CreateBucketConfiguration' get: tags: - s3 summary: Get Bucket Objects operationId: listObjects responses: '200': description: successful list objects content: application/xml: schema: $ref: '#/components/schemas/ListBucketResult' '403': description: Forbidden; Access Denied, InvalidAccessKey, SignatureDoesNotMatch '404': description: Not Found i.e. No Such Bucket delete: tags: - s3 summary: Delete a bucket. operationId: bucketdelete responses: '204': description: No Content i.e. Successful Delete Bucket content: application/xml: schema: $ref: '#/components/schemas/BaseResponse' '403': description: Forbidden; Access Denied, InvalidAccessKey, SignatureDoesNotMatch '404': description: Not Found i.e. No Such Bucket '409': description: Bucket Not Empty '/{bucketName}/{object}': parameters: - name: bucketName in: path description: the name of bucket required: true schema: type: string - name: object in: path description: the name of object required: true schema: type: string - name: Range in: query description: >- the Header parameter Range value like "bytes:1-10",used for multipart download required: false schema: type: string - name: uploads in: query description: The format is ''/{object}?uploads'',used for init multipartupload required: false schema: type: string - name: partNumber in: query description: >- the format is '/{object}?partNumber={partNumber}&uploadId={UploadId}',must be used with uploadId parameter ,used for upload a part required: false schema: type: string - name: uploadId in: query description: >- the format is '/{object}?uploadId={UploadId}',used for compelete multipart upload and abort multiparupload required: false schema: type: string put: tags: - s3 summary: Upload Object. operationId: objectPut responses: '200': description: Successful Upload Object '403': description: Forbidden; Access Denied, InvalidAccessKey, SignatureDoesNotMatch '404': description: Not Found i.e. No Such Bucket get: tags: - s3 summary: Download Object operationId: objectGet responses: '200': description: Successful Download Object '403': description: Forbidden; Access Denied, InvalidAccessKey, SignatureDoesNotMatch '404': description: Not Found i.e. No Such Key delete: tags: - s3 summary: Delete Object. operationId: objectdelete responses: '200': description: Successful Delete Object content: application/xml: schema: $ref: '#/components/schemas/BaseResponse' '403': description: Forbidden; Access Denied, InvalidAccessKey, SignatureDoesNotMatch '404': description: Not Found i.e. No Such Key '/storageClasses': get: tags: - s3 summary: Get Supported StorageClasses operationId: getStorageClasses responses: '200': description: >- Get storage classes succesfully. There is a map between storage class name and stroage tier, as default the storage classes are compatible with aws s3. content: application/xml: schema: $ref: '#/components/schemas/ListStorageClasses' components: parameters: offset: in: query name: offset required: false schema: type: integer minimum: 0 default: 0 description: The number of items to skip before starting to collect the result set limit: in: query name: limit required: false schema: type: integer minimum: 1 default: 1000 description: The numbers of items to return sort: in: query name: sort required: false schema: type: string description: >- The sort key and direction of items to return, string must like:"id:asc,name:desc" schemas: Backend: type: object properties: Id: description: The backend ID, generate by server type: string example: '5ea809d2553b0f000116be32' TenantId: description: The tenant UUID in a multi-tenancy environment. type: string example: '94b280022d0c4401bcf3b0ea85870519' UserId: description: The user UUID in a multi-tenancy environment. type: string example: '558057c4256545bd8a307c37464003c9' Name: description: The backend name specified by user. type: string example: backend001 Type: description: The backend type. type: string example: aws-s3 enum: *CLOUD_BACKENDS Region: type: string example: ap-south-1 Endpoint: type: string example: s3.amazonaws.com BucketName: type: string example: bucket001 Access: type: string example: '4X7JQDFTCYUNWFBRYZVC' Security: type: string example: '9hr0ekZgg0vZHulEekTVfWuu1lnPFvpVAJQNHXdn' Type: type: object properties: name: description: The backend type name. type: string example: aws-s3 description: description: The backend type description. type: string example: AWS Simple Cloud Storage Service(S3) KV: type: object properties: key: description: Key of the Key-Value object. type: string example: Image001.PNG Value: description: Value of the Key-Value object. type: string example: '"d97849a5d11d7f7f90e0c1609d091d0a"' Connector: type: object properties: StorType: $ref: '#/components/schemas/ConnType' BucketName: type: string description: >- The name of bucket which is created in OpenSDS. When the type of connector is opensds-obj, this parameter should be provided. example: bucket001 ConnType: type: string description: Connector type. example: opensds-obj enum: *CLOUD_BACKENDS Plan: type: object properties: Id: description: The plan ID, generate by server type: string example: '5eaa81fd6f384d000116d1d4' TenantId: description: The tenant UUID in a multi-tenancy environment. type: string example: '94b280022d0c4401bcf3b0ea85870519' UserId: description: The user UUID in a multi-tenancy environment. type: string example: '558057c4256545bd8a307c37464003c9' Description: description: Plan description. type: string example: AWS to HW OBS Bucket Migration Name: description: The plan name specified by user. type: string example: plan001 Type: description: >- The plan type. Till now only migration support. New types will be added in the future. type: string example: migration enum: - migration PolicyEnabled: description: Enable policy or not. type: boolean PolicyId: description: >- Related policy id, plan will be scheduled automatically according this policy if PolicyEnabled is true. type: string RemainSource: description: Remain the source objects or not. type: boolean example: true SourceConn: $ref: '#/components/schemas/Connector' DestConn: $ref: '#/components/schemas/Connector' Filter: type: object properties: Prefix: type: string description: >- Prefix of object name, only those objects which name have this prefix will be choosed. example: photos/ Tag: type: array description: Tag of object name. items: $ref: '#/components/schemas/KV' Job: type: object properties: Id: description: The plan ID, generated by server type: string example: '5bd6f273b0bdf90001dc91c3' TenantId: description: The tenant UUID in a multi-tenancy environment. type: string example: '94b280022d0c4401bcf3b0ea85870519' UserId: description: The User UUID in a multi-tenancy environment. type: string example: '558057c4256545bd8a307c37464003c9' TriggerType: description: The migration triggering operation type. type: string example: manual enum: - auto - manual Type: description: >- The plan type. Till now only migration support. New types will be added in the future. type: string example: migration enum: *JOBS PlanName: description: The name of plan job belongs to. type: string example: plan001 PlanId: description: The id of plan job belongs to. type: string example: '5eaa81fd6f384d000116d1d4' SourceLocation: description: The source data migrate or replicate from. type: string example: bucket001 DestLocation: description: The target data migrate or replicate to. type: string example: bucket002 CreateTime: description: The time job is created. type: integer example: 1588233982 StartTime: description: The time job started to run. type: integer example: 158823398 EndTime: description: The time job ended. type: integer example: 1588233983 Status: description: The status of job. type: string enum: - pending - running - succeed - failed example: succeed TotalCapacity: description: The total capacity that should be migrated. type: integer example: 287206 PassedCapacity: description: The capacity that have been migrated. type: integer example: 287206 MigratedCapacity: description: The capacity that have been migrated till now. type: integer example: 287206 TotalCount: description: The total count of objects that should be migrated. type: integer example: 1 PassedCount: description: The count that have been migrated. type: integer example: 1 Progress: description: The progress of job, represented by percentage. type: integer example: 100 RemainSource: description: Flag indicating to keep the content of source bucket type: boolean example: true Policy: type: object properties: Id: description: The policy ID, generate by server type: string example: '5bd6f273b0bdf90001dc91c3' TenantId: description: The tenant UUID in a multi-tenancy environment. type: string example: '94b280022d0c4401bcf3b0ea85870519' Name: description: Policy Name. type: string example: policy001 Description: description: Description of policy. type: string example: Migration Policy Schedule: description: Schedule rules. type: object properties: Type: type: string description: The type of scheduler, only cron support now. enum: - cron example: 'cron' TriggerProperties: type: string description: >- Cron expression format. A cron expression represents a set of times, using 6 space-separated fields as follow. #Field name | Mandatory? | Allowed values | Allowed special characters #---------- | ---------- | -------------- | -------------------------- #Seconds | Yes | 0-59 | * / , - #Minutes | Yes | 0-59 | * / , - #Hours | Yes | 0-23 | * / , - #Day of month | Yes | 1-31 | * / , - ? #Month | Yes | 1-12 or JAN-DEC | * / , - #Day of week | Yes | 0-6 or SUN-SAT | * / , - ? #See https://godoc.org/github.com/robfig/cron for details. example: '' BaseResponse: type: object properties: ErrorCode: description: error code type: string Message: description: sucessfully or failure type: string CreateBucketConfiguration: type: object xml: namespace: http://s3.amazonaws.com/doc/2006-03-01/ properties: LocationConstraint: description: The backend of Bucket type: string example: backend001 ListAllMyBucketsResult: type: object xml: namespace: http://s3.amazonaws.com/doc/2006-03-01/ properties: Owner: description: Owner/Tenant of the bucket type: object properties: ID: description: The tenant UUID in a multi-tenancy environment. type: string example: '94b280022d0c4401bcf3b0ea85870519' DisplayName: description: The tenant name in a multi-tenancy environment. type: string example: '' Buckets: description: '' type: object properties: Bucket: description: Bucket details type: object properties: Name: description: The name of bucket type: string example: bucket001 CreationDate: description: The date of creation type: string example: '2020-04-29T15:37:28.000Z' LocationConstraint: description: The backend of logical bucket type: string example: aws-backend VersioningConfiguration: description: Versioning Configuration of the bucket type: object properties: Status: description: Status of the Versioning Bucket type: string enum: - Enabled - Disabled - Suspended example: Disabled SSEConfiguration: description: SSE Configuration of the bucket type: object properties: SSE: description: SSE Configuration of the bucket type: object properties: enabled: description: Status of the SSE Bucket type: boolean example: false SSE-KMS: description: SSE KMS Configuration of the bucket type: object properties: enabled: description: Status of the SSE KMS Bucket type: boolean example: false DefaultKMSMasterKey: description: Master Key of the SSE KMS Bucket type: string example: '' ListBucketResult: type: object description: Bucket List Metadata properties: Delimiter: description: Delimiter is a character used to group keys type: string example: '' IsTruncated: description: Flag to indicate whether all of the results that satisfied the search criteria is returned type: boolean example: false Marker: description: Indicates where in the bucket listing begins. type: string example: '' NextMarker: description: When response is truncated, key name is used in this field as marker in the subsequent request to get next set of objects. type: string example: '' MaxKeys: description: Maximum number of keys returned in the response body. type: integer example: 1000 Name: description: Bucket Name type: string example: bucket001 Prefix: description: Keys that begin with the indicated prefix type: string example: '' Contents: description: Metadata about each object returned type: object properties: Key: description: The name of the Object type: string example: SODA.PNG LastModified: description: The date the Object was Last Modified type: string example: '2020-04-29T14:11:47.000Z' ETag: description: The entity tag is an MD5 hash of the object. ETag reflects only changes to the contents of an object, not its metadata. type: string example: '"d97849a5d11d7f7f90e0c1609d091d0a"' Size: description: Size in bytes of the object type: integer example: 287206 Owner: description: The owner of the object type: object properties: ID: description: The ID of the owner. type: string example: '94b280022d0c4401bcf3b0ea85870519' DisplayName: description: The display name of the owner. type: string example: '94b280022d0c4401bcf3b0ea85870519' StorageClass: description: The class of storage used to store the object type: string example: STANDARD Tier: description: The storageclass tier for which the object belongs to type: integer example: 1 Location: description: The backend of object type: string example: backend001 ListStorageClasses: type: array xml: wrapped: true items: xml: name: Class type: object properties: Name: description: The storage class name, as default, it is compatible with aws s3. type: string enum: &STORAGE_CLASSES - STANDARD - STANDARD_IA - GLACIER example: STANDARD Tier: description: The storage tier, used in Multi-Cloud. Each tier is mapped to a specific name. type: integer enum: &STORAGE_TIERS - 1 - 99 - 999 example: 1 requestBodies: Backend: content: application/json: schema: $ref: '#/components/schemas/Backend' description: Cloud Backend configurations required: true Plan: content: application/json: schema: $ref: '#/components/schemas/Plan' description: Plan configurations required: true Policy: content: application/json: schema: $ref: '#/components/schemas/Policy' description: Policy configurations required: true