// Copyright 2017 Google Inc.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package google.streetview.publish.v1;

import "google/api/annotations.proto";
import "google/protobuf/empty.proto";
import "google/streetview/publish/v1/resources.proto";
import "google/streetview/publish/v1/rpcmessages.proto";

option go_package = "google.golang.org/genproto/googleapis/streetview/publish/v1;publish";
option java_outer_classname = "StreetViewPublish";
option java_package = "com.google.geo.ugc.streetview.publish.v1";

// Definition of the service that backs the Street View Publish API.



// Publishes and connects user-contributed photos on Street View.
service StreetViewPublishService {
  // Creates an upload session to start uploading photo data. The upload URL of
  // the returned `UploadRef` is used to upload the data for the photo.
  //
  // After the upload is complete, the `UploadRef` is used with
  // `StreetViewPublishService:CreatePhoto()` to create the `Photo` object
  // entry.
  rpc StartUpload(google.protobuf.Empty) returns (UploadRef) {
    option (google.api.http) = { post: "/v1/photo:startUpload" body: "*" };
  }

  // After the client finishes uploading the photo with the returned
  // `UploadRef`, `photo.create` publishes the uploaded photo to Street View on
  // Google Maps.
  //
  // This method returns the following error codes:
  //
  // * `INVALID_ARGUMENT` if the request is malformed.
  // * `NOT_FOUND` if the upload reference does not exist.
  rpc CreatePhoto(CreatePhotoRequest) returns (Photo) {
    option (google.api.http) = { post: "/v1/photo" body: "photo" };
  }

  // Gets the metadata of the specified `Photo`.
  //
  // This method returns the following error codes:
  //
  // * `PERMISSION_DENIED` if the requesting user did not create the requested
  // photo.
  // * `NOT_FOUND` if the requested photo does not exist.
  rpc GetPhoto(GetPhotoRequest) returns (Photo) {
    option (google.api.http) = { get: "/v1/photo/{photo_id}" };
  }

  // Gets the metadata of the specified `Photo` batch.
  //
  // Note that if `photos.batchGet` fails, either critical fields are
  // missing or there was an authentication error.
  // Even if `photos.batchGet` succeeds, there may have been failures
  // for single photos in the batch. These failures will be specified in
  // `BatchGetPhotosResponse.results.status`.
  // See `photo.get` for specific failures that will occur per photo.
  rpc BatchGetPhotos(BatchGetPhotosRequest) returns (BatchGetPhotosResponse) {
    option (google.api.http) = { get: "/v1/photos:batchGet" };
  }

  // Lists all the photos that belong to the user.
  rpc ListPhotos(ListPhotosRequest) returns (ListPhotosResponse) {
    option (google.api.http) = { get: "/v1/photos" };
  }

  // Updates the metadata of a photo, such as pose, place association, etc.
  // Changing the pixels of a photo is not supported.
  //
  // This method returns the following error codes:
  //
  // * `PERMISSION_DENIED` if the requesting user did not create the requested
  // photo.
  // * `INVALID_ARGUMENT` if the request is malformed.
  // * `NOT_FOUND` if the photo ID does not exist.
  rpc UpdatePhoto(UpdatePhotoRequest) returns (Photo) {
    option (google.api.http) = { put: "/v1/photo/{photo.photo_id.id}" body: "photo" };
  }

  // Updates the metadata of photos, such as pose, place association, etc.
  // Changing the pixels of a photo is not supported.
  //
  // Note that if `photos.batchUpdate` fails, either critical fields
  // are missing or there was an authentication error.
  // Even if `photos.batchUpdate` succeeds, there may have been
  // failures for single photos in the batch. These failures will be specified
  // in `BatchUpdatePhotosResponse.results.status`.
  // See `UpdatePhoto` for specific failures that will occur per photo.
  rpc BatchUpdatePhotos(BatchUpdatePhotosRequest) returns (BatchUpdatePhotosResponse) {
    option (google.api.http) = { post: "/v1/photos:batchUpdate" body: "*" };
  }

  // Deletes a photo and its metadata.
  //
  // This method returns the following error codes:
  //
  // * `PERMISSION_DENIED` if the requesting user did not create the requested
  // photo.
  // * `NOT_FOUND` if the photo ID does not exist.
  rpc DeletePhoto(DeletePhotoRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = { delete: "/v1/photo/{photo_id}" };
  }

  // Deletes a list of photos and their metadata.
  //
  // Note that if `photos.batchDelete` fails, either critical fields
  // are missing or there was an authentication error.
  // Even if `photos.batchDelete` succeeds, there may have been
  // failures for single photos in the batch. These failures will be specified
  // in `BatchDeletePhotosResponse.status`.
  // See `photo.update` for specific failures that will occur per photo.
  rpc BatchDeletePhotos(BatchDeletePhotosRequest) returns (BatchDeletePhotosResponse) {
    option (google.api.http) = { post: "/v1/photos:batchDelete" body: "*" };
  }
}