services/space/proto/space.proto

syntax = "proto3";

package space;

option go_package = "./proto;space";

service Space {
	rpc Create(CreateRequest) returns (CreateResponse) {}
	rpc Update(UpdateRequest) returns (UpdateResponse) {}
	rpc Delete(DeleteRequest) returns (DeleteResponse) {}
	rpc List(ListRequest) returns (ListResponse) {}
	rpc Head(HeadRequest) returns (HeadResponse) {}
	rpc Read(ReadRequest) returns (ReadResponse) {}
	rpc Download(DownloadRequest) returns (DownloadResponse) {}
	rpc Upload(UploadRequest) returns (UploadResponse) {}
}

// Create an object. Returns error if object with this name already exists. Max object size of 10MB, see Upload endpoint for larger objects. If you want to update an existing object use the `Update` endpoint
message CreateRequest {
	// The contents of the object. Either base64 encoded if sending request as application/json or raw bytes if using multipart/form-data format
	bytes object = 1;
	// The name of the object. Use forward slash delimiter to implement a nested directory-like structure e.g. images/foo.jpg
	string name = 2;
	// Who can see this object? "public" or "private", defaults to "private"
	string visibility = 3;
}

message CreateResponse {
	// A public URL to access the object if visibility is "public"
	string url = 1;
}

// Update an object. If an object with this name does not exist, creates a new one.
message UpdateRequest {
	// The contents of the object. Either base64 encoded if sending request as application/json or raw bytes if using multipart/form-data format
	bytes object = 1;
	// The name of the object. Use forward slash delimiter to implement a nested directory-like structure e.g. images/foo.jpg
	string name = 2;
	// Who can see this object? "public" or "private", defaults to "private"
	string visibility = 3;
}

message UpdateResponse {
	// A public URL to access the object if visibility is "public"
	string url = 1;
}

// Delete an object from space
message DeleteRequest {
	// Name of the object
	string name = 1;
}

message DeleteResponse {}

// List the objects in space
message ListRequest {
	// optional prefix for the name e.g. to return all the objects in the images directory pass images/
	string prefix = 1;
}

message ListResponse {
	repeated ListObject objects = 1;
}

message ListObject {
	string name = 1;
	// when was this last modified
	string modified = 2;
	string url = 3;
	string visibility = 4;
	string created = 5;
}

// Retrieve meta information about an object
message HeadRequest {
	// name of the object
	string name = 1;
}

message HeadResponse {
	HeadObject object = 1;
}

message HeadObject {
	string name = 1;
	// when was this last modified
	string modified = 2;
	// when was this created
	string created = 3;
	// is this public or private
	string visibility = 4;
	// URL to access the object if it is public
	string url = 5;
}

message SpaceObject {
	// name of object
	string name = 1;
	// when was this last modified
	string modified = 2;
	// when was this created
	string created = 3;
	// is this public or private
	string visibility = 4;
	// URL to access the object if it is public
	string url = 5;
	// the data within the object
	bytes data = 6;
}

// Read an object in space
message ReadRequest {
	// name of the object
	string name = 1;
}

// Returns the raw object
message ReadResponse {
	// The object itself
	SpaceObject object = 1;
}

// Download an object via a presigned url
message DownloadRequest {
	// name of object
	string name = 1;
}

message DownloadResponse {
	// presigned url
	string url = 2;
}

// Upload a large object (> 10MB). Returns a time limited presigned URL to be used for uploading the object
message UploadRequest {
	string name = 1;
	// is this object public or private
	string visibility = 2;
}

message UploadResponse {
	// a presigned url to be used for uploading. To use the URL call it with HTTP PUT and pass the object as the request data
	string url = 1;
}