diff --git a/extensions/workspaces/README.md b/extensions/workspaces/README.md new file mode 100644 index 00000000..2bb2369f --- /dev/null +++ b/extensions/workspaces/README.md @@ -0,0 +1,13 @@ +# Workspaces Extension + +The Workspace Extension to the openEO API provides an interface for connecting external file storage such as cloud buckets to openEO back-end implementations. +It also allows to register such file storage as a data source for new collections, so-called "User Collections". + +- Version: **0.1.0** +- Stability: **experimental** +- [OpenAPI document](openapi.yaml) +- Conformance class: `https://api.openeo.org/extensions/workspaces/0.1.0` + +**Note:** This document only documents the additions to the specification. +Extensions can not change or break existing behavior of the openEO API. + diff --git a/extensions/workspaces/openapi.yaml b/extensions/workspaces/openapi.yaml new file mode 100644 index 00000000..4e8adbfb --- /dev/null +++ b/extensions/workspaces/openapi.yaml @@ -0,0 +1,436 @@ +openapi: 3.0.2 +info: + title: openEO API - Workspaces Extension + version: 0.1.0 + description: |- + The Workspaces Extension to the openEO API provides an interface for connecting external file storage such as cloud buckets to openEO back-end implementations. + + It also allows to register such file storage as a data source for new collections, so-called "User Collections". + contact: + name: openEO Consortium + url: 'https://openeo.org' + email: openeo.psc@uni-muenster.de + license: + name: Apache 2.0 + url: 'http://www.apache.org/licenses/LICENSE-2.0.html' +externalDocs: + url: https://github.com/Open-EO/openeo-api/blob/draft/extensions/workspaces/README.md +tags: + - name: Workspaces + description: Management of User Workspaces + - name: User Collections + description: Management of User Collections +servers: + - url: 'https://openeo.example/api/{version}' + description: >- + The URL of the API MAY freely be chosen by the back-end providers. The + path, including API versioning, is a *recommendation* only. Nevertheless, + all servers MUST support HTTPS as the authentication methods are not + secure with HTTP only! + variables: + version: + default: v1 + description: >- + API versioning is RECOMMENDED. As the openEO API is following + [SemVer](https://semver.org/) only the MAJOR part of the stable + version numbers (i.e. versions >= 1.0.0) SHOULD be used for API + versioning in the URL. The reason is that backward-incompatible + changes are usually introduced by major changes. Therefore, the + version number in the URL MUST not be used by the clients to detect + the version number of the API. Use the version number returned from + `GET /` instead. +paths: + /workspaces: + post: + summary: Create Workspace + operationId: create_workspace_workspaces_post + parameters: + - required: false + schema: + title: Authorization + type: string + name: authorization + in: header + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/WorkspaceCreate' + required: true + responses: + '201': + description: Successful Response + content: + application/json: + schema: {} + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /workspaces/{workspace_name}: + get: + summary: Get Workspace + operationId: get_workspace_workspaces__workspace_name__get + parameters: + - required: true + schema: + title: Workspace Name + pattern: ^demo-user + type: string + name: workspace_name + in: path + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/Workspace' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + delete: + summary: Delete Workspace + operationId: delete_workspace_workspaces__workspace_name__delete + parameters: + - required: true + schema: + title: Workspace Name + pattern: ^demo-user + type: string + name: workspace_name + in: path + responses: + '204': + description: Successful Response + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + patch: + summary: Patch Workspace + operationId: patch_workspace_workspaces__workspace_name__patch + parameters: + - required: true + schema: + title: Workspace Name + pattern: ^demo-user + type: string + name: workspace_name + in: path + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/WorkspaceUpdate' + required: true + responses: + '204': + description: Successful Response + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /workspaces/{workspace_name}/register: + post: + summary: Register + operationId: register_workspaces__workspace_name__register_post + parameters: + - required: true + schema: + title: Workspace Name + pattern: ^demo-user + type: string + name: workspace_name + in: path + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Product' + required: true + responses: + '200': + description: Successful Response + content: + application/json: + schema: {} + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /workspaces/{workspace_name}/deregister: + post: + summary: Deregister + operationId: deregister_workspaces__workspace_name__deregister_post + parameters: + - required: true + schema: + title: Workspace Name + pattern: ^demo-user + type: string + name: workspace_name + in: path + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/DeregisterProduct' + required: true + responses: + '200': + description: Successful Response + content: + application/json: + schema: {} + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /collections: + post: + summary: Register Collection + operationId: register_collection_workspaces__workspace_name__register_collection_post + parameters: + - required: true + schema: + title: Workspace Name + pattern: ^demo-user + type: string + name: workspace_name + in: path + requestBody: + content: + application/json: + schema: + title: Collection + type: object + required: true + responses: + '200': + description: Successful Response + content: + application/json: + schema: {} + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + delete: + summary: Unregister Collection + operationId: register_collection_workspaces__workspace_name__register_collection_post + parameters: + - required: true + schema: + title: Workspace Name + pattern: ^demo-user + type: string + name: workspace_name + in: path + requestBody: + content: + application/json: + schema: + title: Collection + type: object + required: true + responses: + '200': + description: Successful Response + content: + application/json: + schema: {} + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' +components: + schemas: + ContainerRegistryCredentials: + title: ContainerRegistryCredentials + required: + - username + - password + type: object + properties: + username: + title: Username + type: string + password: + title: Password + type: string + CreateContainerRegistryRepository: + title: CreateContainerRegistryRepository + required: + - repository_name + type: object + properties: + repository_name: + title: Repository Name + type: string + DeregisterProduct: + title: DeregisterProduct + required: + - type + type: object + properties: + type: + title: Type + type: string + identifier: + title: Identifier + type: string + url: + title: Url + type: string + Endpoint: + title: Endpoint + required: + - id + - url + type: object + properties: + id: + title: Id + type: string + url: + title: Url + type: string + GrantAccess: + title: GrantAccess + required: + - repository_name + - username + type: object + properties: + repository_name: + title: Repository Name + type: string + username: + title: Username + type: string + HTTPValidationError: + title: HTTPValidationError + type: object + properties: + detail: + title: Detail + type: array + items: + $ref: '#/components/schemas/ValidationError' + Product: + title: Product + required: + - type + - url + type: object + properties: + type: + title: Type + type: string + url: + title: Url + type: string + parent_identifier: + title: Parent Identifier + type: string + Storage: + title: Storage + required: + - credentials + type: object + properties: + credentials: + title: Credentials + type: object + additionalProperties: + type: string + StorageUpdate: + title: StorageUpdate + required: + - quota_in_mb + type: object + properties: + quota_in_mb: + title: Quota In Mb + type: integer + ValidationError: + title: ValidationError + required: + - loc + - msg + - type + type: object + properties: + loc: + title: Location + type: array + items: + anyOf: + - type: string + - type: integer + msg: + title: Message + type: string + type: + title: Error Type + type: string + Workspace: + title: Workspace + required: + - status + type: object + properties: + status: + $ref: '#/components/schemas/WorkspaceStatus' + endpoints: + title: Endpoints + type: array + items: + $ref: '#/components/schemas/Endpoint' + default: [] + storage: + $ref: '#/components/schemas/Storage' + container_registry: + $ref: '#/components/schemas/ContainerRegistryCredentials' + WorkspaceCreate: + title: WorkspaceCreate + type: object + properties: + preferred_name: + title: Preferred Name + type: string + default: '' + default_owner: + title: Default Owner + type: string + default: '' + WorkspaceStatus: + title: WorkspaceStatus + enum: + - ready + - provisioning + description: An enumeration. + WorkspaceUpdate: + title: WorkspaceUpdate + type: object + properties: + storage: + $ref: '#/components/schemas/StorageUpdate' diff --git a/extensions/workspaces/package.json b/extensions/workspaces/package.json new file mode 100644 index 00000000..e9e403c8 --- /dev/null +++ b/extensions/workspaces/package.json @@ -0,0 +1,24 @@ +{ + "name": "@openeo/api-extension-commercial-data", + "version": "0.1.0", + "author": "openEO Consortium", + "license": "Apache-2.0", + "description": "The openEO API specification.", + "homepage": "https://openeo.org", + "bugs": { + "url": "https://github.com/Open-EO/openeo-api/issues" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/Open-EO/openeo-api.git" + }, + "devDependencies": { + "@stoplight/spectral": "^5.9.1", + "redoc-cli": "^0.13.21" + }, + "scripts": { + "start": "redoc-cli serve openapi.yaml --watch --options.expandResponses \"200,201,202,203,204\" --options.pathInMiddlePanel true", + "build": "redoc-cli bundle openapi.yaml -o redoc.html --title \"openEO API - Workspace Extension\" --cdn --options.expandResponses \"200,201,202,203,204\" --options.pathInMiddlePanel true", + "test": "spectral lint openapi.yaml" + } +}