doc/api/keep-s3.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: api
   4 navmenu: API Methods
   5 title: "S3 API"
   6
   7 ...
   8 {% comment %}
   9 Copyright (C) The Arvados Authors. All rights reserved.
  10
  11 SPDX-License-Identifier: CC-BY-SA-3.0
  12 {% endcomment %}
  13
  14 The Simple Storage Service (S3) API is a de-facto standard for object storage originally developed by Amazon Web Services.  Arvados supports accessing files in Keep using the S3 API.
  15
  16 S3 is supported by many "cloud native" applications, and client libraries exist in many languages for programmatic access.
  17
  18 h3. Endpoints and Buckets
  19
  20 To access Arvados S3 using an S3 client library, you must tell it to use the URL of the keep-web server (this is @Services.WebDAVDownload.ExternalURL@ in the public configuration) as the custom endpoint.  The keep-web server will decide to treat it as an S3 API request based on the presence of an AWS-format Authorization header.  Requests without an Authorization header, or differently formatted Authorization, will be treated as "WebDAV":keep-webdav.html .
  21
  22 The "bucket name" is an Arvados collection uuid, portable data hash, or project uuid.
  23
  24 The bucket name must be encoded as the first path segment of every request.  This is what the S3 documentation calls "Path-Style Requests".
  25
  26 h3. Supported Operations
  27
  28 h4. ListObjects
  29
  30 Supports the following request query parameters:
  31
  32 * delimiter
  33 * marker
  34 * max-keys
  35 * prefix
  36
  37 h4. GetObject
  38
  39 Supports the @Range@ header.
  40
  41 h4. PutObject
  42
  43 Can be used to create or replace a file in a collection.
  44
  45 An empty PUT with a trailing slash and @Content-Type: application/x-directory@ will create a directory within a collection if Arvados configuration option @Collections.S3FolderObjects@ is true.
  46
  47 Missing parent/intermediate directories within a collection are created automatically.
  48
  49 Cannot be used to create a collection or project.
  50
  51 h4. DeleteObject
  52
  53 Can be used to remove files from a collection.
  54
  55 If used on a directory marker, it will delete the directory only if the directory is empty.
  56
  57 h4. HeadBucket
  58
  59 Can be used to determine if a bucket exists and if client has read access to it.
  60
  61 h4. HeadObject
  62
  63 Can be used to determine if an object exists and if client has read access to it.
  64
  65 h4. GetBucketVersioning
  66
  67 Bucket versioning is presently not supported, so this will always respond that bucket versioning is not enabled.
  68
  69 h3. Authorization mechanisms
  70
  71 Keep-web accepts AWS Signature Version 4 (AWS4-HMAC-SHA256) as well as the older V2 AWS signature.
  72
  73 * If your client uses V4 signatures exclusively: use the Arvados token's UUID part as AccessKey, and its secret part as SecretKey.  This is preferred.
  74 * If your client uses V2 signatures, or a combination of V2 and V4, or the Arvados token UUID is unknown: use the secret part of the Arvados token for both AccessKey and SecretKey.