Skip to main content

PutObjectCommand

The PutObjectCommand is used to upload a new object or update an existing object in your DID Space. This command is versatile and can handle various data types, such as files, strings, or buffers, making it the primary method for adding content to your space.

Usage Scenario

You should use PutObjectCommand whenever you need to:

  • Upload a new file (e.g., an image, a document, or a configuration file).
  • Create a folder by providing a key that ends with a / and no data.
  • Update the content or metadata of an existing file.

Input

The PutObjectCommand requires the following input parameters to specify the object's location, content, and metadata.

  • key string (required) — The unique identifier for the object, which can be a file path or a folder name. For example, 'path/to/my-file.txt' or 'my-folder/'.
  • data Data — The content of the object. This can be a string, Buffer, Blob, or any other compatible data type. This field is optional if you are creating an empty folder.
  • hash string — An optional hash of the object's content, typically an IPFS v1 CID. This can be used to verify data integrity upon upload.
  • metadata Record<string, any> — An optional object to store custom metadata associated with the object. This is useful for storing application-specific information like content type, author, or custom tags.

Output

The command returns a standard output object after the operation is complete.

  • statusCode number — The HTTP status code of the response. A value of 200 indicates a successful upload.
  • statusMessage string — The HTTP status message corresponding to the status code.
  • data void — This command does not return any data in the response body.

Example: Uploading a Text File

Here's a complete example of how to initialize the SpaceClient and use PutObjectCommand to upload a simple text file.

Example: Uploading a file

typescript
import { SpaceClient, PutObjectCommand } from '@blocklet/did-space-js';
import getWallet from '@blocklet/sdk/lib/wallet';

async function uploadFile() {
  const client = new SpaceClient({
    auth: {
      endpoint: 'https://www.didspaces.com/app/api/space/...',
      wallet: getWallet(),
    },
  });

  const command = new PutObjectCommand({
    key: 'greetings.txt',
    data: 'Hello, DID Space!',
    metadata: {
      contentType: 'text/plain',
      source: 'my-application',
    },
  });

  const output = await client.send(command);

  if (output.statusCode === 200) {
    console.log('File uploaded successfully!');
  } else {
    console.error(`Failed to upload file: ${output.statusCode} ${output.statusMessage}`);
  }
}

uploadFile();

Example Response

Response

json
{
  "statusCode": 200,
  "statusMessage": "OK",
  "data": undefined
}

In this example, a file named greetings.txt with the content "Hello, DID Space!" is uploaded to the root of the space. We also include custom metadata to specify the content type and the source application.

Best Practices

  • Use Metadata: Attaching metadata to your objects is a great way to store additional context without altering the object's content. This can be very useful for filtering, organizing, and processing files later on.
  • Handling Large Files: The SDK handles the complexities of multipart uploads for you. Simply provide the data, and the client will manage the streaming and transfer efficiently.
  • Error Handling: Always check the statusCode in the output to confirm that the upload was successful. A 200 status code means success, while other codes indicate potential issues that your application should handle.