### IAM API - ListPolicies (GET with Query String)

Source: https://github.com/meganz/s4-specs/blob/main/README.md

This example shows how to call the ListPolicies action for the IAM service using a GET request with parameters in the query string.

```APIDOC
## GET /

### Description
Retrieves a list of policies. This is an example of how to use the IAM service with parameters in the query string.

### Method
GET

### Endpoint
/

### Parameters
#### Query Parameters
- **Action** (string) - Required - The name of the IAM action to perform, e.g., `ListPolicies`.
- **Version** (string) - Required - The API version, e.g., `2010-05-08`.
- **AUTHPARAMS** (string) - Required - Authentication parameters.

### Request Example
```http
GET /?Action=ListPolicies&Version=2010-05-08&AUTHPARAMS HTTP/1.1
Host: iam.eu-amsterdam.megas4.com
```
```

--------------------------------

### IAM GET Request with Query Parameters

Source: https://github.com/meganz/s4-specs/blob/main/README.md

Example of an IAM service request using the GET method with parameters in the query string. Ensure 'AUTHPARAMS' is replaced with actual authentication parameters.

```http
GET /?Action=ListPolicies&Version=2010-05-08&AUTHPARAMS HTTP/1.1
Host: iam.eu-amsterdam.megas4.com
```

--------------------------------

### CreateBucket

Source: https://github.com/meganz/s4-specs/blob/main/README.md

Creates a new bucket. The bucket name must be unique within the S4 system. The Host header must start with the bucket name.

```APIDOC
## PUT /

### Description
Creates a new bucket.

### Method
PUT

### Endpoint
/

### Headers
- **Host**: `<bucket_name>.s3.eu-amsterdam.megas4.com` (example)

### Request Body
This endpoint does not support a request body.

### Response
#### Success Response (200 OK)
- **Location** (string) - The location of the created bucket.

### Errors
- **BucketAlreadyOwnedByYou** (409 Conflict): Returned if a bucket with the specified name already exists and is owned by you.
- **InvalidBucketName** (400 Bad Request): Returned if the bucket name does not meet the required restrictions.
- **InternalError** (500 Internal Server Error): Returned due to internal technical reasons.
```

--------------------------------

### IAM Policy Example

Source: https://github.com/meganz/s4-specs/blob/main/README.md

This JSON snippet defines an IAM policy with broad permissions. Use with caution as it grants all actions on all resources.

```json
{
  "Action": "iam:*",
  "Resource": "*"
}
```

--------------------------------

### IAM API - ListPolicies (POST with Body)

Source: https://github.com/meganz/s4-specs/blob/main/README.md

This example demonstrates calling the ListPolicies action for the IAM service using a POST request with parameters encoded in the request body.

```APIDOC
## POST /

### Description
Submits an IAM action, such as listing policies, using a POST request with parameters in the request body.

### Method
POST

### Endpoint
/

### Parameters
#### Query Parameters
- **Action** (string) - Required - The name of the IAM action to perform, e.g., `ListPolicies`.
- **Version** (string) - Required - The API version, e.g., `2010-05-08`.
- **AUTHPARAMS** (string) - Required - Authentication parameters.

### Request Body
- **URL encoded query string** (string) - Required - Contains the action, version, and authentication parameters.

### Request Example
```http
POST / HTTP/1.1
Host: iam.eu-amsterdam.megas4.com

Action=ListPolicies&Version=2010-05-08&AUTHPARAMS
```
```

--------------------------------

### AttachUserPolicy Success Response XML

Source: https://github.com/meganz/s4-specs/blob/main/README.md

Example of a successful response body when attaching a policy to a user.

```xml
<AttachUserPolicyResponse xmlns="https://iam.amazonaws.com/doc/2010-05-08/"> – or AttachGroupPolicyResponse
  <ResponseMetadata>
    <RequestId>0000000000000001</RequestId>
  </ResponseMetadata>
</AttachUserPolicyResponse>
```

--------------------------------

### GET Object

Source: https://github.com/meganz/s4-specs/blob/main/README.md

Retrieves an object from the S4 storage. Supports various URL parameters for controlling the response and conditional GET requests via specific headers.

```APIDOC
## GET /<Key>

### Description
Retrieves an object from S4 storage. The Host header must start with the bucket name (e.g., `test-bucket.s3.eu-amsterdam.megas4.com`). Alternatively, the URL can include the bucket name directly: `/<bucket_name>/<Key>`.

### Method
GET

### Endpoint
`/<Key>` or `/<bucket_name>/<Key>`

### Parameters
#### Query Parameters
- **_response-cache-control** (string) - Optional - Controls the Cache-Control header of the response.
- **response-content-encoding** (string) - Optional - Controls the Content-Encoding header of the response.
- **response-content-language** (string) - Optional - Controls the Content-Language header of the response.
- **response-content-type** (string) - Optional - Controls the Content-Type header of the response.

#### Specific Headers
- **If-Match** (string) - Optional - Ensures the object has not changed since a specific version.
- **If-Modified-Since** (string) - Optional - Retrieves the object only if it has been modified since a specific date.
- **If-None-Match** (string) - Optional - Retrieves the object only if it does not match a specific ETag.
- **If-Unmodified-Since** (string) - Optional - Ensures the object has not been modified since a specific date.
- **Range** (string) - Optional - Specifies a byte range to retrieve from the object.

### Response
#### Success Response (206 Partial Content)
- **Cache-Control** (string) - Present if `_response-cache-control` is used.
- **Content-Disposition** (string) - Present if specified.
- **Content-Encoding** (string) - Present if `response-content-encoding` is used.
- **Content-Language** (string) - Present if `response-content-language` is used.
- **Content-Range** (string) - Present for partial content responses.
- **Content-Type** (string) - Present if `response-content-type` is used.
- **ETag** (string) - The ETag of the object.
- **Expires** (string) - Present if specified.
- **Last-Modified** (string) - The last modified date of the object.
- **x-amz-meta-"key"** (string) - User-defined metadata associated with the object.
```

--------------------------------

### GetPolicyVersion Success Response XML

Source: https://github.com/meganz/s4-specs/blob/main/README.md

Example of a successful response when retrieving a specific policy version. This XML includes the policy document (URL-encoded), version ID, default status, and creation date.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<GetPolicyVersionResponse xmlns="https://iam.amazonaws.com/doc/2010-05-08/">

  <GetPolicyVersionResult>
    <PolicyVersion>
      <Document>
        %7B%22Version%22%3A%222012-10-17%22%2C%22Statement%22%3A%7B%22Effect%22%3A%22Allow%22%2C%22Action%22%3A%22%2A%22%2C%22Resource%22%3A%22%2A%22%7D%7D
      </Document>
      <IsDefaultVersion>true</IsDefaultVersion>
      <VersionId>v1</VersionId>
      <CreateDate>2022-07-29T20:05:50.000Z</CreateDate>
    </PolicyVersion>
  </GetPolicyVersionResult>
  <ResponseMetadata>
    <RequestId>0000000000000017</RequestId>
  </ResponseMetadata>
</GetPolicyVersionResponse>
```

--------------------------------

### IAM POST Request with Body Parameters

Source: https://github.com/meganz/s4-specs/blob/main/README.md

Example of an IAM service request using the POST method with parameters in the request body. The body should be a URL-encoded query string. Ensure 'AUTHPARAMS' is replaced with actual authentication parameters.

```http
GET / HTTP/1.1
Host: iam.eu-amsterdam.megas4.com

Action=ListPolicies&Version=2010-05-08&AUTHPARAMS
```

--------------------------------

### GetPolicy Success Response XML

Source: https://github.com/meganz/s4-specs/blob/main/README.md

Example of a successful response when retrieving policy details. This XML structure contains information about the policy's ARN, attachment count, creation and update dates, and its path.

```xml
<?xml version="1.0" encoding="UTF-8"?>

<GetPolicyResponse xmlns="https://iam.amazonaws.com/doc/2010-05-08/">
  <GetPolicyResult>
    <Policy>
      <Arn>arn:aws:iam::aws:policy/AdministratorAccess</Arn>
      <AttachmentCount>0</AttachmentCount>
      <CreateDate>2022-07-29T20:05:50.000Z</CreateDate>
      <UpdateDate>2022-07-29T20:05:50.000Z</UpdateDate>
      <PolicyId>ADMINISTRATORACCESS</PolicyId>
      <PolicyName>AdministratorAccess</PolicyName>
      <DefaultVersionId>v1</DefaultVersionId>
      <Path>/</Path>
      <IsAttachable>true</IsAttachable>
      <Description></Description>
    </Policy>
  </GetPolicyResult>
  <ResponseMetadata>
    <RequestId>0000000000000003</RequestId>
  </ResponseMetadata>
</GetPolicyResponse>
```

--------------------------------

### S4 S3BucketReadAccess Policy

Source: https://github.com/meganz/s4-specs/blob/main/README.md

Grants permissions to list all buckets and get bucket-related information. Suitable for reading bucket configurations.

```json
{
  "Version": "2012-10-17",
  "Statement": {
    "Effect": "Allow",
    "Action": [
      "s3:ListAllMyBuckets",
      "s3:GetBucket*"
    ],
    "Resource": "*"
  }
}
```

--------------------------------

### S4 IAMReadAccess Policy

Source: https://github.com/meganz/s4-specs/blob/main/README.md

Grants permissions to get and list IAM resources. Suitable for reading IAM configurations and entities.

```json
{
  "Version": "2012-10-17",
  "Statement": {
    "Effect": "Allow",
    "Action": [
      "iam:Get*",
      "iam:List*"
    ],
    "Resource": "*"
  }
}
```

--------------------------------

### S3 Error Format Example

Source: https://github.com/meganz/s4-specs/blob/main/README.md

This XML structure represents a typical S3 error response. It includes a code, a human-readable message, the resource involved, and a request ID.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<Error>
  <Code>NoSuchKey</Code>
  <Message>The specified key does not exist.</Message>
  <Resource>/myobj</Resource>
  <RequestId>HC0000000000000001</RequestId>
</Error>
```

--------------------------------

### AWS IAM ListAttachedUserPolicies Success Response XML

Source: https://github.com/meganz/s4-specs/blob/main/README.md

Example of a successful response body for listing policies attached to an IAM user. Includes policy name and ARN.

```xml
<ListAttachedUserPoliciesResponse xmlns="https://iam.amazonaws.com/doc/2010-05-08/"> -- or ListAttachedGroupPoliciesResponse
  <ListAttachedGroupPoliciesResult> -- or ListAttachedGroupPoliciesResponse
    <AttachedPolicies>
      <member>
        <PolicyName>FullAccess</PolicyName>
        <PolicyArn>arn:aws:iam::aws:policy/FullAccess</PolicyArn>
      </member>
    </AttachedPolicies>
    <IsTruncated>false</IsTruncated>
  </ListAttachedGroupPoliciesResult>
  <ResponseMetadata>
    <RequestId>0000000000000001</RequestId>
  </ResponseMetadata>
</ListAttachedGroupPoliciesResponse>
```

--------------------------------

### AWS IAM ListPolicies Success Response XML

Source: https://github.com/meganz/s4-specs/blob/main/README.md

Example of a successful response body when listing IAM policies. It includes policy details like ARN, name, and creation date.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<ListPoliciesResponse xmlns="https://iam.amazonaws.com/doc/2010-05-08/">
  <ListPoliciesResult>
    <IsTruncated>false</IsTruncated>
    <Policies>
      <member>
        <Arn>arn:aws:iam::aws:policy/FullAccess</Arn>
        <AttachmentCount>0</AttachmentCount>
        <CreateDate>2017-05-15T02:57:50.000Z</CreateDate>
        <UpdateDate>2017-05-15T02:57:50.000Z</UpdateDate>
        <PolicyId>FULLACCESS</PolicyId>
        <PolicyName>FullAccess</PolicyName>
        <DefaultVersionId>v1</DefaultVersionId>
        <Path>/</Path>
        <IsAttachable>true</IsAttachable>
      </member>
       ...
    </Policies>
  </ListPoliciesResult>
  <ResponseMetadata>
    <RequestId>0000000000000001</RequestId>
  </ResponseMetadata>
</ListPoliciesResponse>
```

--------------------------------

### GetBucketLocation

Source: https://github.com/meganz/s4-specs/blob/main/README.md

Retrieves the region where the specified bucket is stored. This operation uses the GET HTTP method.

```APIDOC
## GetBucketLocation

### Description
Retrieves the region where the specified bucket is stored.

### Method
GET

### Endpoint
/?location

### Note
Host header must start with `<bucket_name>`, e.g. `test-bucket.s3.eu-amsterdam.megas4.com`

### Endpoint
/`<bucket_name>`/?location

### Parameters
#### Path Parameters
* None

#### Query Parameters
* None

#### Request Body
* None

### Success Response
#### Success Response (200)
* Status Code: 200 OK
* Body: `<LocationConstraint xmlns="http://s3.amazonaws.com/doc/2006-03-01/">string</LocationConstraint>` (Always an empty string)

### Errors
* None
```

--------------------------------

### CreateBucket

Source: https://github.com/meganz/s4-specs/blob/main/README.md

Creates a new bucket with the specified name if it is valid and does not already exist.

```APIDOC
## CreateBucket

### Description
Creates the bucket `<bucket_name>` if it is a valid bucket name and it does not exist yet.

### Method
PUT (Assumed based on common S3 patterns for creation)

### Endpoint
`/<bucket_name>` (Path Style) or `/<bucket_name>.s3.<endpoint_domain>` (Virtual-Hosted Style)

### Parameters
#### Path Parameters
* **bucket_name** (string) - Required - The name of the bucket to create.

#### Query Parameters
* None

### Request Example
* No request body is typically required for bucket creation.

### Response
#### Success Response (201 Created - Assumed)
* The bucket is created successfully.

#### Response Example
* No specific response body is detailed in the source.

### Errors
* **AccessDenied** or **InvalidBucketName**: Returned if the bucket name fails validation or access is denied.
```

--------------------------------

### DetachUserPolicy Success Response XML

Source: https://github.com/meganz/s4-specs/blob/main/README.md

Example of a successful response body when detaching a policy from a user.

```xml
<DetachUserPolicyResponse xmlns="https://iam.amazonaws.com/doc/2010-05-08/"> – or DetachGroupPolicyResponse
  <ResponseMetadata>
    <RequestId>0000000000000001</RequestId>
  </ResponseMetadata>
</detachUserPolicyResponse>
```

--------------------------------

### Get Object ACL XML Response

Source: https://github.com/meganz/s4-specs/blob/main/README.md

This is the canned XML response for GetObjectAcl. It always returns FULL_CONTROL permission.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<AccessControlPolicy xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> 
  <Owner>
    <ID>string</ID>
    <DisplayName>string</DisplayName>
  </Owner>
  <AccessControlList>
    <Grant>
      <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">
        <ID>string</ID>
        <DisplayName>string</DisplayName>
      </Grantee>
      <Permission>FULL_CONTROL</Permission>   
    </Grant>
  </AccessControlList>
</AccessControlPolicy>
```

--------------------------------

### ListObjects

Source: https://github.com/meganz/s4-specs/blob/main/README.md

Returns a list of all objects in a bucket.

```APIDOC
## ListObjects

### Description
Returns a list of all objects in a bucket.

### Method
GET

### Endpoint
`/{BucketName}`

### Success Response (200)
- **Contents** (array) - A list of object summaries.
  - **Key** (string) - The object key.
  - **LastModified** (datetime) - The date and time the object was last modified.
  - **ETag** (string) - The ETag of the object.
  - **Size** (integer) - The size of the object in bytes.
  - **StorageClass** (string) - The storage class of the object.
```

--------------------------------

### CreateBucket

Source: https://github.com/meganz/s4-specs/blob/main/README.md

Creates a new bucket for the authenticated sender of the request.

```APIDOC
## CreateBucket

### Description
Creates a new bucket for the authenticated sender of the request.

### Method
PUT

### Endpoint
`/{BucketName}`

### Parameters
#### Path Parameters
- **BucketName** (string) - Required - The name of the bucket to create.

### Request Example
(No request body specified in source)

### Success Response (200)
(No success response body specified in source)

### Errors
- **BucketAlreadyExists**: Returned if the bucket with the specified name already exists.
```

--------------------------------

### InitiateMultipartUploadResult XML

Source: https://github.com/meganz/s4-specs/blob/main/README.md

This XML structure represents a successful initiation of a multipart upload. It includes the bucket name, object key, and a unique upload ID.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<InitiateMultipartUploadResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Bucket>string</Bucket>
    <Key>string</Key>
    <UploadId>string</UploadId>
</InitiateMultipartUploadResult>
```

--------------------------------

### PutBucketAcl

Source: https://github.com/meganz/s4-specs/blob/main/README.md

This operation is not supported and will always return an error.

```APIDOC
## PutBucketAcl

### Description
This service is currently not supported and will always return `AccessControlListNotSupported` error (400 Bad Request).

### Method
PUT (Implied, not explicitly stated but typical for ACL operations)

### Endpoint
(Not specified, but typically related to bucket ACLs)

### Parameters
* None explicitly documented for this unsupported operation.

### Request Body
* None explicitly documented for this unsupported operation.

### Success Response
* Not applicable as the service is unsupported.

### Errors
* Error Code: AccessControlListNotSupported
* HTTP Status Code: 400 Bad Request
```

--------------------------------

### S4 S3ReadAccess Policy

Source: https://github.com/meganz/s4-specs/blob/main/README.md

Grants permissions to list and get S3 resources. Suitable for read-only access to objects and buckets.

```json
{
  "Version": "2012-10-17",
  "Statement": {
    "Effect": "Allow",
    "Action": [
      "s3:List*",
      "s3:Get*"
    ],
    "Resource": "*"
  }
}
```

--------------------------------

### ListPolicies

Source: https://github.com/meganz/s4-specs/blob/main/README.md

Lists IAM policies. Supports optional parameters like Marker and MaxItems.

```APIDOC
## ListPolicies

### Description
Lists IAM policies. Supports optional parameters for pagination and filtering.

### Method
GET (assumed, based on operation name and parameters)

### Endpoint
Not explicitly defined.

### Parameters
#### Path Parameters
None explicitly defined.

#### Query Parameters
- **Marker** (string) - Optional - Used for pagination to indicate the starting point of the next set of results.
- **MaxItems** (integer) - Optional - The maximum number of items to return in the response.
- **OnlyAttached** (boolean) - Optional - If true, only lists policies that are attached to an entity. (Note: Marked as not supported in source)
- **PathPrefix** (string) - Optional - Filters policies by path prefix. (Note: Marked as not supported in source)
- **PolicyUsageFilter** (string) - Optional - Filters policies based on usage. (Note: Marked as not supported in source)
- **Scope** (string) - Optional - Filters policies by scope. (Note: Marked as not supported in source)

### Request Example
(No explicit request example provided in source)

### Response
(Response structure not detailed in source)

### Errors
(Error details not provided in source)
```

--------------------------------

### ListParts

Source: https://github.com/meganz/s4-specs/blob/main/README.md

Lists the parts that have been uploaded for a specified multipart upload.

```APIDOC
## ListParts

### Description
Lists the parts that have been uploaded for a specified multipart upload.

### Method
GET

### Endpoint
`/{BucketName}/{ObjectKey}?uploadId=<upload_id>`

### Parameters
#### Path Parameters
- **BucketName** (string) - Required - The name of the bucket.
- **ObjectKey** (string) - Required - The key of the object.

#### Query Parameters
- **uploadId** (string) - Required - The ID of the multipart upload.

### Success Response (200)
- **Parts** (array) - A list of uploaded parts.
  - **PartNumber** (integer) - The part number.
  - **LastModified** (datetime) - The date and time the part was last modified.
  - **ETag** (string) - The ETag of the part.
  - **Size** (integer) - The size of the part in bytes.
```

--------------------------------

### S4 S3ObjectReadAccess Policy

Source: https://github.com/meganz/s4-specs/blob/main/README.md

Grants permissions to get S3 objects and list multipart upload parts. Suitable for reading object data.

```json
{
  "Version": "2012-10-17",
  "Statement": {
    "Effect": "Allow",
    "Action": [
      "s3:GetObject*",
      "s3:ListMultipartUploadParts",
      "s3:ListBucket*"
    ],
    "Resource": "*"
  }
}
```

--------------------------------

### ListObjectsV2

Source: https://github.com/meganz/s4-specs/blob/main/README.md

Returns a list of all objects in a bucket using V2.

```APIDOC
## ListObjectsV2

### Description
Returns a list of all objects in a bucket using V2.

### Method
GET

### Endpoint
`/{BucketName}?list-type=2`

### Success Response (200)
- **Contents** (array) - A list of object summaries.
  - **Key** (string) - The object key.
  - **LastModified** (datetime) - The date and time the object was last modified.
  - **ETag** (string) - The ETag of the object.
  - **Size** (integer) - The size of the object in bytes.
  - **StorageClass** (string) - The storage class of the object.
- **NextContinuationToken** (string) - A token to retrieve the next page of results.
```

--------------------------------

### ListPolicies

Source: https://github.com/meganz/s4-specs/blob/main/README.md

Lists all policies.

```APIDOC
## ListPolicies

### Description
Lists all policies.

### Method
GET

### Endpoint
/listPolicies
```

--------------------------------

### UploadPartCopy

Source: https://github.com/meganz/s4-specs/blob/main/README.md

UploadPartCopy is supported for full object copies only.

```APIDOC
## UploadPartCopy

### Description
UploadPartCopy is supported for full object copies only.

### Method
POST

### Endpoint
/{{bucket}}/{{key}}?partNumber={{partNumber}}&uploadId={{uploadId}}

### Parameters
#### Query Parameters
- **partNumber** (integer) - Required - The part number being uploaded.
- **uploadId** (string) - Required - The upload ID of the multipart upload.

#### Request Headers
- **x-amz-copy-source** (string) - Required - Specifies the bucket and object to copy.
- **x-amz-source-range** (string) - Optional - Specifies the byte range of the object to copy.

### Request Example
```json
{
  "example": "POST /my-bucket/my-object?partNumber=1&uploadId=EXAMPLE12345 HTTP/1.1\nHost: s4.amazonaws.com\nDate: Mon, 27 Jul 2009 12:27:00 GMT\nAuthorization: AWS [AWS Access Key ID]:[Signature]\nx-amz-copy-source: /source-bucket/source-object\nx-amz-source-range: bytes=0-1023"
}
```

### Response
#### Success Response (200 OK)
- **ETag** (string) - The ETag of the copied part.
- **LastModified** (datetime) - The date and time when the part was copied.

#### Response Example
```json
{
  "example": "<CopyPartResult xmlns=\"http://s3.amazonaws.com/doc/2006-03-01/"><LastModified>2009-07-27T12:27:00.000Z</LastModified><ETag>\"a1b2c3d4e5f678901234567890abcdef\"</ETag></CopyPartResult>"
}
```

### Errors
- **400 Bad Request**: Returned for errors like `InvalidPart`, `EntityTooSmall`, `BadDigest`, `InvalidDigest`.
- **404 Not Found**: Returned for `NoSuchUpload`.
- **503 Service Unavailable**: Returned for `ServiceUnavailable`.
- **500 Internal Server Error**: Returned for `InternalError`.
```

--------------------------------

### GetObject

Source: https://github.com/meganz/s4-specs/blob/main/README.md

Retrieves an object from a bucket.

```APIDOC
## GetObject

### Description
Retrieves an object from a bucket.

### Method
GET

### Endpoint
`/{BucketName}/{ObjectKey}`

### Parameters
#### Path Parameters
- **BucketName** (string) - Required - The name of the bucket.
- **ObjectKey** (string) - Required - The key of the object.
```

--------------------------------

### PutObject

Source: https://github.com/meganz/s4-specs/blob/main/README.md

Uploads an object to a bucket.

```APIDOC
## PutObject

### Description
Uploads an object to a bucket.

### Method
PUT

### Endpoint
`/{BucketName}/{ObjectKey}`

### Parameters
#### Path Parameters
- **BucketName** (string) - Required - The name of the bucket.
- **ObjectKey** (string) - Required - The key of the object.

### Request Example
(No request body specified in source)

### Success Response (200)
- **ETag** (string) - The ETag of the uploaded object.
- **LastModified** (datetime) - The date and time the object was last modified.
```

--------------------------------

### CreateMultipartUpload

Source: https://github.com/meganz/s4-specs/blob/main/README.md

Initiates a multipart upload for an object.

```APIDOC
## CreateMultipartUpload

### Description
Initiates a multipart upload for an object.

### Method
POST

### Endpoint
`/{BucketName}/{ObjectKey}?uploads`

### Parameters
#### Path Parameters
- **BucketName** (string) - Required - The name of the bucket.
- **ObjectKey** (string) - Required - The key of the object.

### Success Response (200)
- **Bucket** (string) - The name of the bucket.
- **Key** (string) - The key of the object.
- **UploadId** (string) - The ID of the multipart upload.
```

--------------------------------

### PutBucketPolicy

Source: https://github.com/meganz/s4-specs/blob/main/README.md

Attaches a policy to a bucket.

```APIDOC
## PutBucketPolicy

### Description
Attaches a policy to a bucket.

### Method
PUT

### Endpoint
/putBucketPolicy
```

--------------------------------

### CreateMultipartUpload

Source: https://github.com/meganz/s4-specs/blob/main/README.md

Initiates a multipart upload. This operation is used to upload a single object as a set of parts. You can upload parts in any order. You must know the upload ID before you can commit or abort the upload.

```APIDOC
## CreateMultipartUpload

### Description
Initiates a multipart upload. This operation is used to upload a single object as a set of parts. You can upload parts in any order. You must know the upload ID before you can commit or abort the upload.

### Method
POST

### Endpoint
/{{bucketName}}/{{objectKey}}?uploads

### Parameters
#### Query Parameters
- **uploads** (string) - Required - This parameter is used to initiate the multipart upload.

### Request Example
```json
{
  "example": "POST /my-bucket/my-object?uploads HTTP/1.1\nHost: example.com\nDate: Mon, 28 Nov 2022 10:00:00 GMT\nAuthorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE,SignedHeaders=host;x-amz-content-sha256,Signature=example..."
}
```

### Response
#### Success Response (200)
- **Bucket** (string) - The name of the bucket to which the object will be uploaded.
- **Key** (string) - The name of the object to be uploaded.
- **UploadId** (string) - The unique identifier for the multipart upload.

#### Response Example
```json
{
  "Bucket": "my-bucket",
  "Key": "my-object",
  "UploadId": "V1VjYXRpb25JZGVudGlmaWVyMTIzNDU2Nzg5MA=="
}
```
```

--------------------------------

### S4 S3ListAccess Policy

Source: https://github.com/meganz/s4-specs/blob/main/README.md

Allows listing S3 resources. Useful for inventory or discovery tasks.

```json
{
  "Version": "2012-10-17",
  "Statement": {
    "Effect": "Allow",
    "Action": "s3:List*",
    "Resource": "*"
  }
}
```

--------------------------------

### ListObjects

Source: https://github.com/meganz/s4-specs/blob/main/README.md

Lists objects within a specified bucket. This endpoint supports various query parameters for filtering and pagination of the object list.

```APIDOC
## GET /

### Description
List objects in `<bucket_name>`.

### Method
GET

### Endpoint
/

### Parameters
#### Path Parameters
* None

#### Query Parameters
* **delimiter** (string) - Supported
* **encoding-type** (string) - Supported
* **marker** (string) - Supported
* **max-keys** (integer) - Supported
* **prefix** (string) - Supported

#### Request Body
* None

### Request Example
```json
{
  "example": "No request body"
}
```

### Response
#### Success Response (200 OK)
* The response body will contain a list of objects and their metadata. (Specific schema not provided in source)

#### Response Example
```json
{
  "example": "Response structure not detailed in source"
}
```

### Errors
* **NoSuchBucket**: Returned in case `<bucket_name>` does not exist. (404 Not Found)
* **InternalError**: Returned due to technical reasons. (500 Internal Server Error)
```

--------------------------------

### S4 S3BucketListAccess Policy

Source: https://github.com/meganz/s4-specs/blob/main/README.md

Allows listing all S3 buckets. Useful for an overview of available buckets.

```json
{
  "Version": "2012-10-17",
  "Statement": {
    "Effect": "Allow",
    "Action": "s3:ListAllMyBuckets",
    "Resource": "*"
  }
}
```

--------------------------------

### Object Upload

Source: https://github.com/meganz/s4-specs/blob/main/README.md

This endpoint allows for the upload of objects to the S4 storage system. It supports various headers for metadata and content configuration.

```APIDOC
## POST /<Key>

### Description
Uploads an object to the S4 storage system. The Host header must be prefixed with the bucket name, e.g., `test-bucket.s3.eu-amsterdam.megas4.com`.

### Method
POST

### Endpoint
- `/<Key>`
- `/<bucket_name>/<Key>`

### URL Params
- `uploads`: Supported

### Specific Headers
- `Cache-Control`: Supported
- `Content-Disposition`: Supported
- `Content-Encoding`: Supported
- `Content-Language`: Supported
- `Content-Type`: Supported
- `Expires`: Supported
- `x-amz-meta-*`: Supported

### Body
No specific body is defined; typically contains the object data.
```

--------------------------------

### ListBuckets

Source: https://github.com/meganz/s4-specs/blob/main/README.md

Retrieves a list of all buckets owned by the requester.

```APIDOC
## ListBuckets

### Description
Retrieves a list of all buckets owned by the requester.

### Method
GET

### Endpoint
/

### Parameters
#### Path Parameters
* None

#### Query Parameters
* None

### Request Example
* No request body is required.

### Response
#### Success Response (200 OK)
* Returns an XML document containing a list of buckets and their creation dates, along with owner information.

#### Response Example
```xml
<?xml version="1.0" encoding="UTF-8"?>
<ListAllMyBucketsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Buckets>
    <Bucket>
      <CreationDate>2022-01-28T11:44:13Z</CreationDate>
      <Name>bucket1</Name>
    </Bucket>
    <Bucket>
      <CreationDate>2022-02-15T18:22:37Z</CreationDate>
      <Name>bucket2</Name>
    </Bucket>
  </Buckets>
  <Owner>
    <ID>57A54E56B89C54B767F01987C0BC77929B5212C0BF165E3CF2B8DF818C46B66C</ID>
    <DisplayName>158563168473704</DisplayName>
  </Owner>
</ListAllMyBucketsResult>
```

### Errors
* No specific errors are expected.
```

--------------------------------

### CopyObject

Source: https://github.com/meganz/s4-specs/blob/main/README.md

Copies an object from one bucket to another.

```APIDOC
## CopyObject

### Description
Copies an object from one bucket to another.

### Method
PUT

### Endpoint
`/{DestinationBucketName}/{DestinationObjectKey}`

### Parameters
#### Path Parameters
- **DestinationBucketName** (string) - Required - The name of the destination bucket.
- **DestinationObjectKey** (string) - Required - The key of the destination object.

#### Request Body
- **CopySource** (string) - Required - The source object to copy, specified as `/{SourceBucketName}/{SourceObjectKey}`.
```

--------------------------------

### S3 Virtual-Hosted Style Object Identification

Source: https://github.com/meganz/s4-specs/blob/main/README.md

For virtual-hosted style object identification, the object key is in the URL path, while the bucket name is in the Host header.

```http
GET /<key> HTTP/1.1.
Host: <bucket_name>.s3.eu-amsterdam.megas4.com
```

--------------------------------

### UploadPartCopy

Source: https://github.com/meganz/s4-specs/blob/main/README.md

Copies a part of an object from one location to another as part of a multipart upload.

```APIDOC
## UploadPartCopy

### Description
Copies a part of an object from one location to another as part of a multipart upload.

### Method
PUT

### Endpoint
`/{BucketName}/{ObjectKey}?partNumber=<part_number>&uploadId=<upload_id>`

### Parameters
#### Path Parameters
- **BucketName** (string) - Required - The name of the bucket.
- **ObjectKey** (string) - Required - The key of the object.

#### Query Parameters
- **partNumber** (integer) - Required - The part number.
- **uploadId** (string) - Required - The ID of the multipart upload.

#### Request Body
- **CopySource** (string) - Required - The source object to copy, specified as `/{SourceBucketName}/{SourceObjectKey}`.
```

--------------------------------

### S4 S3BucketWriteAccess Policy

Source: https://github.com/meganz/s4-specs/blob/main/README.md

Allows creating and putting bucket-related configurations. Use for managing bucket settings.

```json
{
  "Version": "2012-10-17",
  "Statement": {
    "Effect": "Allow",
    "Action": [
      "s3:CreateBucket",
      "s3:PutBucket*"
    ],
    "Resource": "*"
  }
}
```

--------------------------------

### List Multipart Uploads

Source: https://github.com/meganz/s4-specs/blob/main/README.md

Retrieves a list of multipart uploads that have been initiated but not yet completed or aborted.

```APIDOC
## GET /?uploads

### Description
Lists multipart uploads.

### Method
GET

### Endpoint
/?uploads

### Parameters
#### Query Parameters
- **delimiter** (string) - Optional - Used to group uploaded objects by a common prefix.
- **encoding-type** (string) - Optional - Specifies the encoding method for the output.
- **key-marker** (string) - Optional - Marks the end of the list of keys returned in the previous response.
- **max-uploads** (integer) - Optional - Sets the maximum number of multipart uploads to return in the response.
- **prefix** (string) - Optional - Filters the list of uploads to return only those that begin with the specified prefix.
- **upload-id-marker** (string) - Optional - Marks the end of the list of uploads returned in the previous response.

### Request Example
(No request body)

### Response
#### Success Response (200 OK)
- **Bucket** (string) - The name of the bucket.
- **Upload** (object) - Contains details about an initiated multipart upload.
  - **Key** (string) - The key of the object being uploaded.
  - **UploadId** (string) - The ID of the multipart upload.
  - **StorageClass** (string) - The storage class of the object (always "STANDARD").
  - **Initiated** (timestamp) - The timestamp when the upload was initiated.
- **MaxUploads** (integer) - The maximum number of uploads returned in the response.
- **IsTruncated** (boolean) - Indicates if the list of uploads is truncated.
- **KeyMarker** (string) - The marker for the next key.
- **UploadIdMarker** (string) - The marker for the next upload ID.
- **NextKeyMarker** (string) - The next key marker to use for pagination.
- **NextUploadIdMarker** (string) - The next upload ID marker to use for pagination.

#### Response Example
```xml
<?xml version="1.0" encoding="UTF-8"?>
<ListMultipartUploadsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Bucket>string</Bucket>
    <Upload>
        <Key>string</Key>
        <UploadId>string</UploadId>
        <StorageClass>string</StorageClass>   🟠 – Always set to "STANDARD"
        <Initiated>timestamp</Initiated>
    </Upload>
    ...
    <MaxUploads>integer</MaxUploads>
    <IsTruncated>boolean</IsTruncated>
    <KeyMarker>string</KeyMarker>
    <UploadIdMarker>string</UploadIdMarker>
    <NextKeyMarker>string</NextKeyMarker>
    <NextUploadIdMarker>string</NextUploadIdMarker>
</ListMultipartUploadsResult>
```

### Errors
- **InvalidArgument** (400 Bad Request) - Returned in case upload-id-marker is invalid.
```

--------------------------------

### HeadBucket

Source: https://github.com/meganz/s4-specs/blob/main/README.md

Determines whether a bucket exists and the caller has permission to access it.

```APIDOC
## HeadBucket

### Description
Determines whether a bucket exists and the caller has permission to access it.

### Method
HEAD

### Endpoint
`/{BucketName}`

### Parameters
#### Path Parameters
- **BucketName** (string) - Required - The name of the bucket to check.
```

--------------------------------

### ListMultipartUploads

Source: https://github.com/meganz/s4-specs/blob/main/README.md

Lists in-progress multipart uploads.

```APIDOC
## ListMultipartUploads

### Description
Lists in-progress multipart uploads.

### Method
GET

### Endpoint
/listMultipartUploads
```

--------------------------------

### ListParts

Source: https://github.com/meganz/s4-specs/blob/main/README.md

Retrieves a list of parts for a multipart upload. Supports filtering by max parts and part number marker.

```APIDOC
## GET /<Key>

### Description
Retrieves a list of parts for a multipart upload. This endpoint can be accessed using alternative URL formats.

### Method
GET

### Endpoint
- `/<Key>`
- `/<bucket_name>/<Key>`

### Parameters
#### Query Parameters
- **uploadId** (string) - Required - The ID of the upload.
- **max-parts** (integer) - Optional - The maximum number of parts to return.
- **part-number-marker** (integer) - Optional - Specifies the part number to start the listing from.

### Request Example
```http
GET /my-object.txt?uploadId=ExampleUploadId HTTP/1.1
Host: test-bucket.s3.eu-amsterdam.megas4.com

```

### Response
#### Success Response (200)
- The response body will contain a list of parts associated with the upload.

#### Response Example
```json
{
  "example": "response body"
}
```
```

--------------------------------

### PutObject Operation

Source: https://github.com/meganz/s4-specs/blob/main/README.md

Creates a new object with the provided contents.

```APIDOC
## PutObject

### Description
Creates a new object with the provided contents.

### Method
POST

### Endpoint
/objects

### Request Body
- **content** (binary) - Required - The content of the object to be created.

### Response
#### Success Response (201 Created)
- **object_id** (string) - The unique identifier of the newly created object.
```

--------------------------------

### Copy Object

Source: https://github.com/meganz/s4-specs/blob/main/README.md

This endpoint allows for copying objects within the S4 storage system. It supports various URL parameters and specific headers for controlling the copy operation.

```APIDOC
## PUT /<Key>

### Description
Copies an object to a new location or with different properties.

### Method
PUT

### Endpoint
- `/<Key>`
- `/<bucket_name>/<Key>`

### Parameters
#### Path Parameters
- **Key** (string) - The key of the object to be copied.
- **bucket_name** (string) - The name of the bucket where the object resides.

#### Query Parameters
- **uploadId** (string) - Required - Used for multipart uploads.
- **partNumber** (string) - Required - Specifies the part number for multipart uploads.

#### Specific Headers
- **Host** - Must start with `<bucket_name>`, e.g., `test-bucket.s3.eu-amsterdam.megas4.com`.
- **x-amz-copy-source** (string) - Required - The source object to copy (bucket/object/key format).
- **x-amz-copy-source-range** (string) - Optional - Specifies a byte range to copy from the source object.

### Request Example
```json
{
  "example": "No request body is expected for this operation."
}
```

### Response
#### Success Response (200 OK)
- **ETag** (string) - The ETag of the copied object.
- **LastModified** (timestamp) - The last modified date of the copied object.

#### Response Example
```xml
<CopyPartResult>
   <ETag>string</ETag>
   <LastModified>timestamp</LastModified>
</CopyPartResult>
```
```

--------------------------------

### Success Response XML for ListParts

Source: https://github.com/meganz/s4-specs/blob/main/README.md

This XML structure represents a successful response when listing parts of a multipart upload. It includes details about the bucket, key, upload ID, and individual part information.

```xml
<ListPartsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
   <Bucket>string</Bucket>
   <Key>string</Key>
   <UploadId>string</UploadId>
   <PartNumberMarker>integer</PartNumberMarker>
   <NextPartNumberMarker>integer</NextPartNumberMarker>
   <MaxParts>integer</MaxParts>
   <IsTruncated>boolean</IsTruncated>
   <Part>
      <PartNumber>integer</PartNumber>
      <LastModified>timestamp</LastModified>
      <ETag>string</ETag>
      <Size>integer</Size>
   </Part>
   ...
   <Initiator>
      <ID>string</ID>
      <DisplayName>string</DisplayName>
   </Initiator>
   <Owner>
      <ID>string</ID>
      <DisplayName>string</DisplayName>
   </Owner>
   <StorageClass>string</StorageClass>       🟠 – Always set to "STANDARD"
   <ChecksumAlgorithm>string</ChecksumAlgorithm>     🔴 - NOT supported
   <ChecksumType>string</ChecksumType>     🔴 - NOT supported
</ListPartsResult>
```

--------------------------------

### PutBucketPolicy

Source: https://github.com/meganz/s4-specs/blob/main/README.md

Applies a policy to a bucket, controlling access to its objects. The policy must be provided in JSON format.

```APIDOC
## PUT PutBucketPolicy

### Description
Applies a policy to a bucket. The policy is provided in JSON format in the request body.

### Method
PUT

### Endpoint
- `/?policy`
- `/<bucket_name>/?policy`

### Parameters
#### Headers
- **Content-MD5** (string) - Mandatory - The MD5 hash of the request body.

#### Request Body
- **Policy** (JSON) - Required - The bucket policy in JSON format.

### Request Example
```
PUT /?policy HTTP/1.1
Host: test-bucket.s3.eu-amsterdam.megas4.com
Content-MD5: <ContentMD5>
Content-Type: application/json

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AddPerm",
      "Effect": "Allow",
      "Action": [
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::test-bucket"
      ],
      "Principal": {
        "AWS": [
          "arn:aws:iam::123456789012:root"
        ]
      }
    }
  ]
}
```

### Response
#### Success Response (200 OK)
- **Body**: The response body is empty.
```

--------------------------------

### HeadBucket

Source: https://github.com/meganz/s4-specs/blob/main/README.md

Determines if a bucket exists and if the user has access to it. This operation uses the HEAD HTTP method.

```APIDOC
## HeadBucket

### Description
Determines if the bucket `<bucket_name>` exists and you have access to it.

### Method
HEAD

### Endpoint
/

### Note
Host header must start with `<bucket_name>`, e.g. `test-bucket.s3.eu-amsterdam.megas4.com`

### Endpoint
/`<bucket_name>`

### Parameters
#### Path Parameters
* None

#### Query Parameters
* None

#### Request Body
* None

### Success Response
#### Success Response (200)
* Status Code: 200 OK
* Body: Empty

### Errors
#### Error Response (400 Bad Request)
* Error Code: InvalidBucketName
* Description: Returned in case `<bucket_name>` does not satisfy restrictions.

#### Error Response (500 Internal Server Error)
* Error Code: InternalError
* Description: Returned due to internal technical reason.

#### Error Response (409 Conflict)
* Error Code: BucketNotEmpty
* Description: Returned if called on a non-empty bucket.
```