Skip to content

Latest commit

 

History

History
297 lines (282 loc) · 11.4 KB

API.md

File metadata and controls

297 lines (282 loc) · 11.4 KB

OVE Asset Manager REST API

This API is designed to allow you to perform the majority of necessary file operations using a REST API

  • /api/list:
    • GET: Lists available file stores
    • Response:
      • Success:
        HTTP Code: 200
        Content: ['store1', 'store2', '...']
  • /api/{store_id}/list
    • GET: Lists available projects in a file store
    • Query params:
      • filterByTag=<tag_name> - optional, filter all projects tagged by tag_name
      • metadata=true | false - optional, if true the project list include some metadata
    • Response:
      • Success:
        HTTP Code: 200
        Content: [{name: "project1", "creationDate": "date"}, "..."]
      • Store not found:
        HTTP Code: 400 Bad Request
        Content: {title="Store not found", description="..."}

  • /api/{store_id}/create

    • POST: Create project
    • Data Params: Requires JSON body

    { "id":"project_id", "name":"project_name" "groups":["group1", "group2"] }

    • Response:
      • Success:
        HTTP Code: 200
        Content: {'Project': project_id}
      • Error: Store not found
        HTTP Code: 400 Bad Request
        Content: {title="Store not found", description="..."}
      • Error: Project already exists
        HTTP Code: 409 Conflict
        Content: {title="Project already in use", description="..."}
    • Notes: With S3 storage, the project name must conform to s3 bucket name conventions
  • /api/{store_id}/{project_id}/list
    • GET: Lists available assets in a file store with meta data
    • Query params:
      • includeEmpty=(True|False) - optional, if true all folders are included regardless of whether they are ove assets`
      • filterByTag=<tag_name> - optional, filter all assets tagged by tag_name
    • Response:
      • Success:
        HTTP Code: 200
        Content: { "Assets" : ["Asset1"] }
      • Store not found:
        HTTP Code: 400 Bad Request
        Content: {title="Store not found", description="..."}
      • Project not found:
        HTTP Code: 400 Bad Request
        Content: {title="Project not found", description="..."}

  • /api/{store_id}/{project_id}/create

    • POST: Create asset
    • Data Params: Requires JSON body

    { "name":"asset_id" }

    • Response:
      • Success:
        HTTP Code: 200
        Content: {'Asset': asset_id}
      • Error: Store not found
        HTTP Code: 400 Bad Request
        Content: {title="Store not found", description="..."}
      • Project not found:
        HTTP Code: 400 Bad Request
        Content: {title="Project not found", description="..."}
      • Error: Asset already exists
        HTTP Code: 409 Conflict
        Content: {title="Asset already in use", description="..."}
    • Notes: _With S3 storage, asset name is not allowed to contain / or any restricted asset names (e.g. new, .ovemeta, list, create)
  • /api/{store_id}/{project_id}/object/{object_id}
    • HEAD: Check if an object exists
    • Response:
      • Success: HTTP Code 200
      • Not found: HTTP Code 404
    • GET: Get an object in JSON format
    • Response:
      • Success:
        HTTP Code: 200
        Content: { ... }
      • Store not found:
        HTTP Code: 400 Bad Request
        Content: {title="Store not found", description="..."}
      • Project not found:
        HTTP Code: 400 Bad Request
        Content: {title="Project not found", description="..."}
      • Object not found:
        HTTP Code: 400 Bad Request
        Content: {title="Object not found", description="..."}
    • POST: Create an object in JSON format
    • Data Params: { ... }
    • Response:
      • Success:
        HTTP Code: 200
        Content: { ... }
      • Store not found:
        HTTP Code: 400 Bad Request
        Content: {title="Store not found", description="..."}
      • Project not found:
        HTTP Code: 400 Bad Request
        Content: {title="Project not found", description="..."}
      • Object not found:
        HTTP Code: 400 Bad Request
        Content: {title="Object not found", description="..."}
      • Object already in use:
        HTTP Code: 400 Bad Request
        Content: {title="Object already in use", description="..."}
    • PUT: Update an object in JSON format
    • Data Params: { ... }
    • Response:
      • Success:
        HTTP Code: 200
        Content: { ... }
      • Store not found:
        HTTP Code: 400 Bad Request
        Content: {title="Store not found", description="..."}
      • Project not found:
        HTTP Code: 400 Bad Request
        Content: {title="Project not found", description="..."}
      • Object not found:
        HTTP Code: 400 Bad Request
        Content: {title="Object not found", description="..."}
  • /api/{store_id}/{project_id}/object/{object_id}/info
    • GET: Get the object metadata
    • Response:
      • Success:
        HTTP Code: 200
        Content: { name="...", index_file="..."}
      • Store not found:
        HTTP Code: 400 Bad Request
        Content: {title="Store not found", description="..."}
      • Project not found:
        HTTP Code: 400 Bad Request
        Content: {title="Project not found", description="..."}
      • Object not found:
        HTTP Code: 400 Bad Request
        Content: {title="Object not found", description="..."}
  • /api/{store_id}/{project_id}/meta/{asset_id}
    • HEAD: Check if an asset exists
    • Response:
      • Success: HTTP Code 200
      • Not found: HTTP Code 404
    • GET: Get an asset metadata
    • Response:
      • Success:
        HTTP Code: 200
        Content: { "name": "...", "project": "...", "description": "...", "index_file": "...", "version": "...", "history": "...", "tags": "...", "worker": "...", "processing_status": "...", "processing_error": "..." }
      • Store not found:
        HTTP Code: 400 Bad Request
        Content: {title="Store not found", description="..."}
      • Project not found:
        HTTP Code: 400 Bad Request
        Content: {title="Project not found", description="..."}
      • Asset not found:
        HTTP Code: 400 Bad Request
        Content: {title="Asset not found", description="..."}
    • POST: Update a project metadata
    • Data Params: {"description": "...", "tags": "..."}
    • Response:
      • Success:
        HTTP Code: 200
        Content: {"Status": "OK"}
      • Store not found:
        HTTP Code: 400 Bad Request
        Content: {title="Store not found", description="..."}
      • Project not found:
        HTTP Code: 400 Bad Request
        Content: {title="Project not found", description="..."}
      • Asset not found:
        HTTP Code: 400 Bad Request
        Content: {title="Asset not found", description="..."}
  • /api/{store_id}/{project_id}/files/{asset_id}
    • GET: list of files under the current version of the asset
    • Response:
      • Success:
        HTTP Code: 200
        Content: [{name: "...", url: "..."}]
      • Store not found:
        HTTP Code: 400 Bad Request
        Content: {title="Store not found", description="..."}
      • Project not found:
        HTTP Code: 400 Bad Request
        Content: {title="Project not found", description="..."}
      • Asset not found:
        HTTP Code: 400 Bad Request
        Content: {title="Asset not found", description="..."}
  • /api/{store_id}/{project_id}/upload/{asset_id}
    • POST: Upload an asset
    • Query params:
      • filename= urlencoded string - required, the filename to upload into the asset
      • create=true | false - optional, if true the asset will be created on upload (default: false)
      • update=true | false - optional, if true the asset will be updated on upload (default: false)
    • Headers: content-disposition: filename="<file_name>"
    • Body: the file octet stream
    • Response:
      • Success:
        HTTP Code: 200
        Content: {"Status": "OK"}
      • Store not found:
        HTTP Code: 400 Bad Request
        Content: {title="Store not found", description="..."}
      • Project not found:
        HTTP Code: 400 Bad Request
        Content: {title="Project not found", description="..."}
      • Asset not found:
        HTTP Code: 400 Bad Request
        Content: {title="Asset not found", description="..."}
      • Asset exists:
        HTTP Code: 409 Conflict
        Content: {title="Asset exists", description="..."}
  • /api/workers
    • GET: Worker list
    • Response:
      • Success:
        HTTP Code: 200
        Content: ['worker1', ...]
    • DELETE: Unregister a worker
    • Data Params: { name: "..." }
    • Response:
      • Success:
        HTTP Code: 200
        Content: { 'Status': 'OK' }
      • Worker not found:
        HTTP Code: 400 Bad Request
        Content: {title="Worker not found", description="..."}
  • /api/workers/queue
    • GET: Get current worker queue
    • Response:
      • Success:
        HTTP Code: 200
        Content: [{task metadata}]
    • POST: Schedule worker task
    • Data Params: { "worker_type": "...", "store_id": "...", "project_id": "...", "asset_id": "...", }
    • Response:
      • Success:
        HTTP Code: 200
        Content: { 'Status': 'OK' }
    • DELETE: Cancel task
    • Data Params: { task_id: "..." }
    • Response:
      • Success:
        HTTP Code: 200
        Content: { 'Status': 'OK' }
    • PATCH: Reset task status
    • Data Params: { task_id: "..." }
    • Response:
      • Success:
        HTTP Code: 200
        Content: { 'Status': 'OK' }