// Custom options of the M-Files gRPC API. They describe facts about services and methods that
// standard protobuf options cannot express. Clients do not need them to call the API; they are
// read by documentation tools and are available to code generators.
syntax = "proto3";

package mfiles.api;

import "google/protobuf/descriptor.proto";

option csharp_namespace = "MFiles.Grpc.Api";
option go_package = "github.com/M-Files/mfiles-grpc-api/go/mfiles/api;mfilesapi";
option java_multiple_files = true;
option java_package = "com.mfiles.grpc.api";

// How a call is authenticated.
enum SessionRequirement {

	// Not specified.
	SESSION_REQUIREMENT_UNSPECIFIED = 0;

	// The call needs no session. It can be made before logging in.
	SESSION_REQUIREMENT_NONE = 1;

	// The call needs a session: the session ID from LogIn in the mfiles-session-id-bin metadata.
	SESSION_REQUIREMENT_SESSION = 2;

	// The call needs a session, or a session assertion in the x-mf-session-assertion metadata.
	SESSION_REQUIREMENT_SESSION_OR_ASSERTION = 3;
}

// Facts about a method.
message MethodInfo {

	// How the call is authenticated.
	SessionRequirement session = 1;

	// Reserved for caching information.
	reserved 2;

	// The response carries the vault's metadata structure version in the
	// mfiles-metadata-version-bin trailer.
	bool returns_metadata_structure_version = 3;

	// Reserved for HTTP mapping information.
	reserved 4, 5;

	// The method is shown first in its service's documentation.
	bool highlighted = 6;

	// The method serves M-Files' own components and is not meant for applications. It can change
	// or be removed without notice.
	bool internal = 7;
}

// Importance level of a service in the documentation.
enum Level {

	// Not specified.
	LEVEL_UNSPECIFIED = 0;

	// The main developer journeys: documented in the most depth.
	LEVEL_CORE = 1;

	// The rest of the end-user API.
	LEVEL_STANDARD = 2;

	// Administration and server-integration services.
	LEVEL_SPECIALIZED = 3;
}

// Facts about a service.
message ServiceInfo {

	// The book of the documentation the service belongs to: vault, admin or integration.
	string book = 1;

	// The importance level of the service.
	Level level = 2;

	// A short human-readable title.
	string title = 3;
}

extend google.protobuf.MethodOptions {

	// Facts about the method.
	MethodInfo method = 51761;
}

extend google.protobuf.ServiceOptions {

	// Facts about the service.
	ServiceInfo service = 51761;
}