forked from kubeflow/model-registry
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Define the Model Registry OpenAPI (kubeflow#51)
* Define the Model Registry OpenAPI Co-authored-by: Andrea Lamparelli <a.lamparelli95@gmail.com> * Update api/openapi/modelregistry.yml Co-authored-by: Andrea Lamparelli <a.lamparelli95@gmail.com> --------- Co-authored-by: Andrea Lamparelli <a.lamparelli95@gmail.com>
- Loading branch information
Showing
1 changed file
with
369 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,369 @@ | ||
| openapi: 3.0.2 | ||
| info: | ||
| title: Model Registry API | ||
| version: 1.0.0 | ||
| description: 'See also https://github.com/opendatahub-io/model-registry/issues/44#issue-1919724627' | ||
| paths: | ||
| /environments: | ||
| summary: Path used to manage the list of environments. | ||
| description: >- | ||
| The REST endpoint/path used to list and create zero or more `Environment` entities. This path | ||
| contains a `GET` and `POST` operation to perform the list and create tasks, respectively. | ||
| get: | ||
| responses: | ||
| '200': | ||
| content: | ||
| application/json: | ||
| schema: | ||
| type: array | ||
| items: | ||
| $ref: '#/components/schemas/Environment' | ||
| description: Successful response - returns an array of `Environment` entities. | ||
| operationId: getEnvironments | ||
| summary: List All Environments | ||
| description: Gets a list of all `Environment` entities. | ||
| post: | ||
| requestBody: | ||
| description: A new `Environment` to be created. | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: '#/components/schemas/Environment' | ||
| required: true | ||
| responses: | ||
| '201': | ||
| description: Successful response. | ||
| operationId: createEnvironment | ||
| summary: Create a Environment | ||
| description: Creates a new instance of a `Environment`. | ||
| delete: | ||
| parameters: | ||
| - | ||
| name: name | ||
| description: '' | ||
| schema: {} | ||
| in: query | ||
| responses: | ||
| '200': | ||
| description: Successfully deleted `Environment` having `name`. | ||
| summary: Delete an Environment | ||
| description: 'Placed here only to avoid subpaths, can be re-drawn.' | ||
| /search: | ||
| description: |- | ||
| TBD: We feel this might be redundant with `models/` and `models/{name}`. | ||
| We suggest instead to: | ||
| 1. avoid usage of Query param (that might "explode" as search grows) | ||
| 2. provide search criteria in the body | ||
| get: | ||
| responses: | ||
| '200': | ||
| content: | ||
| application/json: | ||
| schema: | ||
| type: array | ||
| items: | ||
| $ref: '#/components/schemas/RegisteredModel' | ||
| description: Get all `RegisteredModel`s matching the supplied criteria. | ||
| summary: Search models | ||
| parameters: | ||
| - | ||
| name: name | ||
| description: '' | ||
| schema: | ||
| type: string | ||
| in: query | ||
| - | ||
| name: id | ||
| description: '' | ||
| schema: | ||
| type: string | ||
| in: query | ||
| - | ||
| name: tag | ||
| description: '' | ||
| schema: | ||
| type: string | ||
| in: query | ||
| - | ||
| name: label | ||
| description: '' | ||
| schema: | ||
| type: string | ||
| in: query | ||
| /models: | ||
| get: | ||
| responses: | ||
| '200': | ||
| content: | ||
| application/json: | ||
| schema: | ||
| type: array | ||
| items: | ||
| $ref: '#/components/schemas/RegisteredModel' | ||
| description: List all | ||
| summary: List all Models | ||
| description: List all `RegisteredModel` and belonging `VersionedModel`(s). | ||
| post: | ||
| requestBody: | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: '#/components/schemas/VersionedModel' | ||
| required: true | ||
| responses: | ||
| '200': | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: '#/components/schemas/VersionedModel' | ||
| description: Successfully created a `VersionedModel` for a Registered model. | ||
| summary: Assign a version to a registered model | ||
| description: |- | ||
| If a `RegisteredModel` for `model_name` already exists, this `VersionedModel` | ||
| will be assigned to it, else a new `RegisteredModel` will be created. | ||
| If a `model_name` is not provided, a random one will be used. | ||
| The `id` is generated in the backend by the registry. | ||
| It could be implemented as a progressive number, to be decided. | ||
| The `id`s are unique within a RegisteredModel. | ||
| The `version` is a user-provided symbolic name, for instance semantic versioning | ||
| The `version` if provided must be unique and non-already-existing within a | ||
| RegisterdModel and must not be the same as any of the `id`s. | ||
| '/models/{name}/versions/{version}': | ||
| get: | ||
| responses: | ||
| '200': | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: '#/components/schemas/VersionedModel' | ||
| description: get `VersionedModel` for model name and version | ||
| summary: Get Version details | ||
| delete: | ||
| responses: | ||
| '200': | ||
| description: Successfully archive a `VersionedModel`. | ||
| summary: Archive a VersionedModel | ||
| description: 'This does NOT delete any `VersionedModel`, but archives and deprecate it.' | ||
| patch: | ||
| requestBody: | ||
| description: 'The `uri`, `id`, `version` and other non-updatable fields will be ignored.' | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: '#/components/schemas/VersionedModel' | ||
| required: true | ||
| responses: | ||
| '200': | ||
| description: Successfully upated a `VersionedModel` in the updatable and provided fields. | ||
| description: |- | ||
| Updates a `VersionedModel` only for the updatable fields, such as label, tags, | ||
| description. | ||
| Some fields will not be updated even if supplied, such as `model_uri`, `id`, | ||
| `version`. | ||
| parameters: | ||
| - | ||
| name: name | ||
| schema: | ||
| type: string | ||
| in: path | ||
| required: true | ||
| - | ||
| name: version | ||
| schema: | ||
| type: string | ||
| in: path | ||
| required: true | ||
| '/models/{name}': | ||
| get: | ||
| responses: | ||
| '200': | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: '#/components/schemas/RegisteredModel' | ||
| description: Retrieves the `RegisteredModel`. | ||
| summary: Return a given RegisteredModel | ||
| post: | ||
| requestBody: | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: '#/components/schemas/VersionedModel' | ||
| responses: | ||
| '200': | ||
| description: Successfully registered a versionedmodel under a registered model. | ||
| summary: Register a VersionedModel under a given name | ||
| description: |- | ||
| TBD: this as a potential alternative or complementary of `/models` POST | ||
| where the model's name is provided as a Path param instead. | ||
| parameters: | ||
| - | ||
| name: name | ||
| schema: | ||
| type: string | ||
| in: path | ||
| required: true | ||
| components: | ||
| schemas: | ||
| Environment: | ||
| title: Root Type for Environment | ||
| description: '' | ||
| type: object | ||
| properties: | ||
| name: | ||
| type: string | ||
| uri: | ||
| type: string | ||
| example: | ||
| name: My Environment | ||
| uri: 'http://localhost:8080' | ||
| RegisteredModel: | ||
| title: Root Type for RegisteredModel | ||
| description: '' | ||
| type: object | ||
| properties: | ||
| name: | ||
| type: string | ||
| labels: | ||
| type: array | ||
| items: | ||
| type: string | ||
| versions: | ||
| type: array | ||
| items: | ||
| $ref: '#/components/schemas/VersionedModel' | ||
| example: | ||
| name: my ML pricing model | ||
| labels: | ||
| - tutorial | ||
| - linreg | ||
| versions: | ||
| - | ||
| model_name: my ML pricing model | ||
| id: ae123-78932-64893 | ||
| version: v1 | ||
| model_uri: 's3://89492-46893-54692' | ||
| tags: | ||
| - Staging | ||
| labels: | ||
| - tutorial | ||
| - linreg | ||
| environments: | ||
| - | ||
| name: My Environment | ||
| uri: 'http://localhost:8080' | ||
| created date: '20231002T12:34:56' | ||
| updated date: '20231002T12:34:56' | ||
| author: 'John Doe, data scientist' | ||
| origin: 'dsp://123' | ||
| metadata: | ||
| accuracy: 99 | ||
| artifacts: | ||
| - | ||
| name: dataset | ||
| type: csv | ||
| uri: 's3://67489-46393-63469' | ||
| metadata: | ||
| authority: US Census | ||
| VersionedModel: | ||
| title: Root Type for VersionedModel | ||
| description: '' | ||
| required: | ||
| - model_uri | ||
| type: object | ||
| properties: | ||
| id: | ||
| type: string | ||
| version: | ||
| type: string | ||
| tags: | ||
| type: array | ||
| items: | ||
| type: string | ||
| labels: | ||
| type: array | ||
| items: | ||
| type: string | ||
| environments: | ||
| type: array | ||
| items: | ||
| $ref: '#/components/schemas/Environment' | ||
| created date: | ||
| format: date-time | ||
| type: string | ||
| updated date: | ||
| format: date-time | ||
| type: string | ||
| model_name: | ||
| type: string | ||
| author: | ||
| description: '' | ||
| type: string | ||
| example: '"John Doe, data scientist"' | ||
| metadata: | ||
| description: '' | ||
| type: object | ||
| model_uri: | ||
| description: '' | ||
| type: string | ||
| artifacts: | ||
| description: '' | ||
| type: array | ||
| items: | ||
| $ref: '#/components/schemas/Artifact' | ||
| origin: | ||
| description: 'For instance, the DSP id which realized the model' | ||
| type: string | ||
| example: | ||
| model_name: my ML pricing model | ||
| id: ae123-78932-64893 | ||
| version: v1 | ||
| model_uri: 's3://89492-46893-54692' | ||
| tags: | ||
| - Staging | ||
| labels: | ||
| - tutorial | ||
| - linreg | ||
| environments: | ||
| - | ||
| name: My Environment | ||
| uri: 'http://localhost:8080' | ||
| created date: '20231002T12:34:56' | ||
| updated date: '20231002T12:34:56' | ||
| author: 'John Doe, data scientist' | ||
| origin: 'dsp://123' | ||
| metadata: | ||
| accuracy: 99 | ||
| artifacts: | ||
| - | ||
| name: dataset | ||
| type: csv | ||
| uri: 's3://67489-46393-63469' | ||
| metadata: | ||
| authority: US Census | ||
| Artifact: | ||
| title: Root Type for Artifact | ||
| description: '' | ||
| type: object | ||
| properties: | ||
| type: | ||
| type: string | ||
| uri: | ||
| type: string | ||
| metadata: | ||
| type: object | ||
| properties: | ||
| authority: | ||
| type: string | ||
| name: | ||
| description: '' | ||
| type: string | ||
| example: | ||
| name: dataset | ||
| type: csv | ||
| uri: 's3://67489-46393-63469' | ||
| metadata: | ||
| authority: US Census |