Example of an resource oriented design protobuf file

library.proto

syntax = "proto3";
package bayer.csgda.principalengineering.examples.library.v1;

import "google/api/annotations.proto";
import "google/protobuf/field_mask.proto";
import "google/protobuf/timestamp.proto";

// Customer is a customer can have a number of books on loan
message Customer {
  // resource name format "customers/{uuid}"
  string name = 1;
  // first name of the customer
  string first_name = 2;
  // last name of the customer
  string last_name = 3;
  // date of birth of the customer, in the format of an RFC-3339 timestamp wth zero hours, minutes and seconds
  string date_of_birth = 4;
  // annotations allow for custom field additions to the customer to keep track of
  // data related to the the customer that hasn't been formally codified in another way
  map<string, string> annotations = 5;
  // phone numbers for the customer
  repeated Phone phones = 6;
  // revision is a unique identifier for the resource at a point and time
  string revision = 7;
  // etag is a hash of the resource that represents a unique state unrelated to time.  this value is used for ensuring
  // updates to the resource don't overwrite any changes made by other consumers on accident, i.e. optimistic locking of the
  // resource during update operations
  string etag = 8;
  // audit information captured when the resource was created
  csgda.core.v1.AuditInfo created = 9;
  // audit information captured when the resource was last updated, also set on initial creation
  csgda.core.v1.AuditInfo updated = 10;
  // audit information captured when the resource was deleted
  csgda.core.v1.AuditInfo deleted = 11;

  message Phone {
    // the phone number
    string number = 1;
    // a boolean value indicating that the number was verified
    bool verified = 2;
  }
}

// Book is a record pointing to a book in the library
message Book {
  // resource name of the book in the format "books/{uuid}"
  string name = 1;
  // title of the book
  string title = 2;
  // isbn number
  string isbn_number = 3;
  // array of authors
  repeated string authors = 4;
  // description of the book
  string description = 6;
  // annotations allow for custom field additions to the book to keep track of
  // data related to the the book that hasn't been formally codified in another way
  map<string, string> annotations = 8;
  // revision is a unique identifier for the resource at a point and time
  string revision = 9;
  // etag is a hash of the resource that represents a unique state unrelated to time.  this value is used for ensuring
  // updates to the resource don't overwrite any changes made by other consumers on accident, i.e. optimistic locking of the
  // resource during update operations
  string etag = 10;
  // audit information captured when the resource was created
  csgda.core.v1.AuditInfo created = 11;
  // audit information captured when the resource was last updated, also set on initial creation
  csgda.core.v1.AuditInfo updated = 12;
  // audit information captured when the resource was deleted
  csgda.core.v1.AuditInfo deleted = 13;
}

// Loan is a loan of a book to the customer
message Loan {
  //resource name of the loan in the format of books/{uuid}/loans/{uuid}
  string name = 1;
  // resource name of the parent book, format book/{uuid}
  string parent = 2;
  // resource name of the customer the loan was issued to, format customer/{uuid}
  string customer = 3;
  // RFC-3339 timestamp for when the loan is due
  google.protobuf.Timestamp due_at = 4;
  // RFC-3339 timestamp for when the loaned item was returned
  google.protobuf.Timestamp returned_on = 5;
  // status
  Status status = 6;
  // annotations allow for custom field additions to the book to keep track of
  // data related to the the book that hasn't been formally codified in another way
  map<string, string> annotations = 7;
  // revision is a unique identifier for the resource at a point and time
  string revision = 8;
  // etag is a hash of the resource that represents a unique state unrelated to time.  this value is used for ensuring
  // updates to the resource don't overwrite any changes made by other consumers on accident, i.e. optimistic locking of the
  // resource during update operations
  string etag = 9;
  // audit information captured when the resource was created
  csgda.core.v1.AuditInfo created = 10;
  // audit information captured when the resource was last updated, also set on initial creation
  csgda.core.v1.AuditInfo updated = 11;
  // audit information captured when the resource was deleted
  csgda.core.v1.AuditInfo deleted = 12;
  enum Status {
    STATUS_UNSPECIFIED = 0;
    STATUS_LOANED = 1;
    STATUS_RETURNED = 2;
    STATUS_DESTROYED = 3;
  }
}

// Customer service
service Customers {
  // get a customer
  rpc Get(CustomersGetRequest) returns (CustomersGetResponse) {
    option (google.api.http) = {get: "/v1/{name=customers/*}"};
  }
  // list customers by filter criteria
  rpc List(CustomersListRequest) returns (CustomersListResponse) {
    option (google.api.http) = {get: "/v1/customers"};
  }
  // create a customer
  rpc Create(CustomersCreateRequest) returns (CustomersCreateResponse) {
    option (google.api.http) = {
      post: "/v1/customers"
      body: "customer"
    };
  }
  // Update a customer
  rpc Update(CustomersUpdateRequest) returns (CustomersUpdateResponse) {
    option (google.api.http) = {
      patch: "/v1/{name=customers/*}"
      body: "customer"
    };
  }
  // logically delete a customer
  rpc Delete(CustomersDeleteRequest) returns (CustomersDeleteResponse) {
    option (google.api.http) = {delete: "/v1/{name=customers/*}"};
  }
  // get a point in time revision for a customer
  rpc GetRevision(CustomersGetRevisionRequest) returns (CustomersGetRevisionResponse) {
    option (google.api.http) = {get: "/v1/{name=customers/*/revisions/*"};
  }
  // list revisions of a customer
  rpc ListRevisions(CustomersListRevisionsRequest) returns (CustomersListRevisionsResponse) {
    option (google.api.http) = {get: "v1/name=customers/*/revisions"};
  }
}

// Loans service
service Loans {
  // get a loan
  rpc Get(LoansGetRequest) returns (LoansGetResponse) {
    option (google.api.http) = {get: "/v1/{name=books/*loans/*}"};
  }
  // list loans by filter criteria
  rpc List(LoansListRequest) returns (LoansListResponse) {
    option (google.api.http) = {get: "/v1/{book=books/*}/loans"};
  }
  // create a loan
  rpc Create(LoansCreateRequest) returns (LoansCreateResponse) {
    option (google.api.http) = {
      post: "/v1/{book=books/*}/loans"
      body: "loan"
    };
  }
  // Update a loan
  rpc Update(LoansUpdateRequest) returns (LoansUpdateResponse) {
    option (google.api.http) = {
      patch: "/v1/{name=/v1/books/*loans/*}"
      body: "loan"
    };
  }
  // logically delete a loan
  rpc Delete(LoansDeleteRequest) returns (LoansDeleteResponse) {
    option (google.api.http) = {delete: "/v1/{name=books/*/loans/*}"};
  }
  // get a point in time revision for a loan
  rpc GetRevision(LoansGetRevisionRequest) returns (LoansGetRevisionResponse) {
    option (google.api.http) = {get: "/v1/{name=books/*loans/*/revisions/*"};
  }
  // list revisions of a loan
  rpc ListRevisions(LoansListRevisionsRequest) returns (LoansListRevisionsResponse) {
    option (google.api.http) = {get: "v1/{name=books/*/loans/*}/revisions"};
  }
}

// Books Service
service Books {
  // get a book
  rpc Get(BooksGetRequest) returns (BooksGetResponse) {
    option (google.api.http) = {get: "/v1/{name=books/*}"};
  }
  // list books by filter criteria
  rpc List(BooksListRequest) returns (BooksListResponse) {
    option (google.api.http) = {get: "/v1/books"};
  }
  // create a book
  rpc Create(BooksCreateRequest) returns (BooksCreateResponse) {
    option (google.api.http) = {
      post: "/v1/books"
      body: "book"
    };
  }
  // Update a book
  rpc Update(BooksUpdateRequest) returns (BooksUpdateResponse) {
    option (google.api.http) = {
      patch: "/v1/{name=books/*}"
      body: "book"
    };
  }
  // logically delete a book
  rpc Delete(BooksDeleteRequest) returns (BooksDeleteResponse) {
    option (google.api.http) = {delete: "/v1/{name=books/*}"};
  }
  // get a point in time revision for a book
  rpc GetRevision(BooksGetRevisionRequest) returns (BooksGetRevisionResponse) {
    option (google.api.http) = {get: "/v1/{name=books/*/revisions/*}"};
  }
  // list revisions of a book
  rpc ListRevisions(BooksListRevisionsRequest) returns (BooksListRevisionsResponse) {
    option (google.api.http) = {get: "v1/{name=books/*}/revisions"};
  }
  // checkout custom method
  rpc Checkout(BooksCheckoutRequest) returns (BooksCheckoutResponse) {
    option (google.api.http) = {post: "/v1/{name=books/*}:checkout"};
  }
}

message CustomersGetRequest {
  // resource name "customers/{uuid}"
  string name = 1;
  // show deleted customers, if false, a logically deleted customer will
  // return a not-found error
  bool show_deleted = 2;
  // field mask to apply to the response
  google.protobuf.FieldMask field_mask = 3;
}

message CustomersGetResponse {
  // customer
  Customer customer = 1;
}

message CustomersListRequest {
  message Filter {
    // filter by first names (first_name contains provided values)
    repeated string first_name = 1;
    // filter by last names (last_name contains provided values)
    repeated string last_name = 2;
    // filter by date of birth
    repeated string date_of_birth = 3;
    // filter by annotations, rest format = annotations.key=value
    map<string, string> annotations = 4;
    // filter by phone number (contains)
    repeated string phones = 5;
  }
  // filters
  Filter filter = 1;
  // show deleted entries
  bool show_deleted = 2;
  // field mask to apply to the results
  google.protobuf.FieldMask field_mask = 3;
  // page size
  int32 page_size = 4;
  // page token from previous page requests
  string page_token = 5;
}

message CustomersListResponse {
  // customers matching provided list filters
  repeated Customer customers = 1;
  // next page token, used to fetch next page of customers if results have more pages
  // an emply next page token indicates the end of the list
  string next_page_token = 2;
}

message CustomersCreateRequest {
  message Spec {
    // first name
    string first_name = 1;
    // last name
    string last_name = 2;
    // date of birth
    string date_of_birth = 3;
    // annotations
    map<string, string> annotations = 4;
    // phone numbers
    repeated Customer.Phone phones = 5;
  }
  // customer to create
  Spec customer = 1;
  // field mask to apply to the response
  google.protobuf.FieldMask field_mask = 2;
  // request id to identify the request
  optional string request_id = 3;
}

message CustomersCreateResponse {
  // created customer
  Customer customer = 1;
}
message CustomersUpdateRequest {
  message Spec {
    // first name
    string first_name = 1;
    // last name
    string last_name = 2;
    // date of birth
    string date_of_birth = 3;
    // annotations
    map<string, string> annotations = 4;
    // phone numbers
    repeated Customer.Phone phones = 5;
  }
  // resource name of the customer being updated
  string name = 1;
  // customer data to update
  Spec customer = 2;
  // etag of the customer to update
  string etag = 3;
  // fields to update
  google.protobuf.FieldMask update_mask = 4;
  // field mask to apply to the response
  google.protobuf.FieldMask field_mask = 5;
}

message CustomersUpdateResponse {
  // updated customer
  Customer customer = 1;
}

message CustomersDeleteRequest {
  // resource name "customers/{uuid}"
  string name = 1;
  // etag of the customer to delete
  string etag = 2;
  // field mask to apply to the response
  google.protobuf.FieldMask field_mask = 3;
}

message CustomersDeleteResponse {
  // deleted customer
  Customer customer = 1;
}

message CustomersGetRevisionRequest {
  // resource name "customers/{uuid}/revisions/{uuid}"
  string name = 1;
  // field mask to apply to the response
  google.protobuf.FieldMask field_mask = 3;
}

message CustomerRevision {
  // revision resource name "customers/{uuid}/revisions/{uuid}"
  string revision = 1;
  // resource name of the customer "customers/{uuid}"
  string customer = 2;
  // updated at timestamp
  google.protobuf.Timestamp updated_at = 3;
  // snapshot of the customer at the time of the revision
  Customer snapshot = 4;
  // update mask used to create the revision
  google.protobuf.FieldMask update_mask = 5;
}

message CustomersGetRevisionResponse {
  // customer revision
  CustomerRevision revision = 1;
}

message CustomersListRevisionsRequest {
  message Filter {
    // filter by customer names
    repeated string names = 1;
  }
  // filter
  Filter filter = 1;
  // page token from previous page requests
  string page_token = 2;
  // page size  to return
  int32 page_size = 3;
  // field mask to apply to the response
  google.protobuf.FieldMask field_mask = 4;
}

message CustomersListRevisionsResponse {
  // customer revisions
  repeated CustomerRevision revisions = 1;
  // next page token, used to fetch next page of revisions if results have more pages
  string next_page_token = 2;
}

message LoansGetRequest {
  // resource name "books/{uuid}/loans/{uuid}"
  string name = 1;
  // show deleted loans, if false, a logically deleted loan will return a not-found error
  bool show_deleted = 2;
  // field mask to apply to the response
  google.protobuf.FieldMask field_mask = 3;
}

message LoansGetResponse {
  // loan
  Loan loan = 1;
}

message LoansListRequest {
  message Filter {
    // filter by book resource names (books/{uuid})
    repeated string books = 1;
    // filter by customer resource names (customers/{uuid})
    repeated string customers = 2;
    // filter by status
    repeated Loan.Status status = 3;
  }
  // filter criteria
  Filter filter = 1;
  // show deleted entries in the list results
  bool show_deleted = 2;
  // field mask to apply to the response
  google.protobuf.FieldMask field_mask = 3;
  // page size
  int32 page_size = 4;
  // page token from previous page requests
  string page_token = 5;
}

message LoansListResponse {
  // loans matching provided list filters
  repeated Loan loans = 1;
  // next page token, used to fetch next page of loans if results have more pages
  string next_page_token = 2;
}

message LoansCreateRequest {
  message Spec {
    // customer resource name (customers/{uuid})
    string customer = 1;
    // book resource name (books/{uuid})
    string book = 2;
    // due at timestamp
    google.protobuf.Timestamp due_at = 3;
    // returned on timestamp
    google.protobuf.Timestamp returned_on = 4;
    // status of the loan
    Loan.Status status = 5;
    // annotations
    map<string, string> annotations = 6;
  }
  // loan to create
  Spec loan = 1;
  // field mask to apply to the response
  google.protobuf.FieldMask field_mask = 2;
  // request id to identify the request
  optional string request_id = 3;
}

message LoansCreateResponse {
  // created loan
  Loan loan = 1;
}
message LoansUpdateRequest {
  message Spec {
    // due at timestamp
    google.protobuf.Timestamp due_at = 1;
    // returned on timestamp
    google.protobuf.Timestamp returned_on = 2;
    // status of the loan
    Loan.Status status = 3;
    // annotations
    map<string, string> annotations = 4;
  }
  // resource name of the loan to update, "books/{uuid}/loans/{uuid}"
  string name = 1;
  // loan to update
  Spec loan = 2;
  // etag of the loan to update
  string etag = 3;
  // fields to update
  google.protobuf.FieldMask update_mask = 4;
  // field mask to apply to the response
  google.protobuf.FieldMask field_mask = 5;
}

message LoansUpdateResponse {
  // updated loan
  Loan loan = 1;
}

message LoansDeleteRequest {
  // resource name "books/{uuid}/loans/{uuid}"
  string name = 1;
  // etag of the loan to delete
  string etag = 2;
  // field mask to apply to the response
  google.protobuf.FieldMask field_mask = 3;
}

message LoansDeleteResponse {
  // deleted loan
  Loan loan = 1;
}

message LoansGetRevisionRequest {
  // resource name "books/{uuid}/loans/{uuid}/revisions/{uuid}"
  string name = 1;
  // field mask to apply to the response
  google.protobuf.FieldMask field_mask = 3;
}

message LoanRevision {
  // revision resource name "books/{uuid}/loans/{uuid}/revisions/{uuid}"
  string revision = 1;
  // resource name of the loan "books/{uuid}/loans/{uuid}"
  string loan = 2;
  // updated at timestamp
  google.protobuf.Timestamp updated_at = 3;
  // snapshot of the loan at the time of the revision
  Loan snapshot = 4;
  // update mask used to create the revision
  google.protobuf.FieldMask update_mask = 5;
}

message LoansGetRevisionResponse {
  // loan revision
  LoanRevision revision = 1;
}

message LoansListRevisionsRequest {
  message Filter {
    // filter by loan resource names (books/{uuid}/loans/{uuid})
    repeated string names = 1;
  }
  // filter criteria
  Filter filter = 1;
  // page token from previous page requests
  string page_token = 2;
  // page size  to return
  int32 page_size = 3;
  // field mask to apply to the response
  google.protobuf.FieldMask field_mask = 4;
}

message LoansListRevisionsResponse {
  // loan revisions
  repeated LoanRevision revisions = 1;
  // next page token, used to fetch next page of revisions if results have more pages
  string next_page_token = 2;
}

message BooksGetRequest {
  // resource name "books/{uuid}"
  string name = 1;
  // show deleted books, if false, a logically deleted book will return a not-found error
  bool show_deleted = 2;
  // field mask to apply to the response
  google.protobuf.FieldMask field_mask = 3;
}

message BooksGetResponse {
  // book
  Book book = 1;
}

message BooksListRequest {
  message Filter {
    // filter by book names format "books/{uuid}"
    repeated string names = 1;
    // filter by isbn number
    repeated string isbn_numbers = 2;
    // filter by title
    repeated string titles = 3;
  }
  // filter criteria
  Filter filter = 1;
  // show deleted entries in the list results
  bool show_deleted = 2;
  // field mask to apply to the response
  google.protobuf.FieldMask field_mask = 3;
  // page size
  int32 page_size = 4;
  // page token from previous page requests
  string page_token = 5;
}

message BooksListResponse {
  // books matching provided list filters
  repeated Book custoemrs = 1;
  // next page token, used to fetch next page of books if results have more pages
  string next_page_token = 2;
}

// Request message for creating a book.
message BooksCreateRequest {
  message Spec {
    // The title of the book
    string title = 1;
    // The ISBN number of the book
    string isbn_number = 2;
    // The authors of the book
    repeated string authors = 3;
    // The description of the book
    string description = 4;
    // Annotations for the book
    map<string, string> annotations = 5;
  }
  // The book to create
  Spec book = 1;
  // The fields to be included in the response
  google.protobuf.FieldMask field_mask = 2;
  // An request ID to identify requests
  string request_id = 3;
}

// Response message for creating a book.
message BooksCreateResponse {
  // The created book
  Book book = 1;
}

// Request message for updating a book.
message BooksUpdateRequest {
  message Spec {
    // The title of the book
    string title = 1;
    // The ISBN number of the book
    string isbn_number = 2;
    // The authors of the book
    repeated string authors = 3;
    // The description of the book
    string description = 4;
    // Annotations for the book
    map<string, string> annotations = 5;
  }
  // resource name of the book to update "books/{uuid}"
  string name = 1;
  // The book data to update
  Spec book = 2;
  // The eta of the book
  string etag = 3;
  // The fields to update
  google.protobuf.FieldMask update_mask = 4;
  // The fields to be included in the response
  google.protobuf.FieldMask field_mask = 5;
}

// Response message for updating a book.
message BooksUpdateResponse {
  // The updated book
  Book book = 1;
}

// Request message for deleting a book.
message BooksDeleteRequest {
  // The name of the book to delete format "books/{uuid}"
  string name = 1;
  // The etag of the book
  string etag = 2;
  // The fields to be included in the response
  google.protobuf.FieldMask field_mask = 3;
}

// Response message for deleting a book.
message BooksDeleteResponse {
  // The deleted book
  Book book = 1;
}

message BooksGetRevisionRequest {
  // The name of the book revision format "books/{uuid}/revisions/{uuid}"
  string name = 1;
  // The fields to be included in the response
  google.protobuf.FieldMask field_mask = 3;
}

message BookRevision {
  // The revision of the book format "books/{uuid}/revisions/{uuid}"
  string revision = 1;
  // The resource name of the book format "books/{uuid}"
  string book = 2;
  // The updated at timestamp
  google.protobuf.Timestamp updated_at = 3;
  // The snapshot of the book at the time of the revision
  Book snapshot = 4;
  // The update mask used to create the revision
  google.protobuf.FieldMask update_mask = 5;
}

message BooksGetRevisionResponse {
  // The book revision
  BookRevision revision = 1;
}

message BooksListRevisionsRequest {
  message Filter {
    // Filter by book names format "books/{uuid}"
    repeated string names = 1;
  }
  // Filter criteria
  Filter filter = 1;
  // Page token from previous page requests
  string page_token = 2;
  // Page size  to return
  int32 page_size = 3;
  // Field mask to apply to the response
  google.protobuf.FieldMask field_mask = 4;
}
message BooksCheckoutRequest {
  // resource name of the book, format "books/{uuid}"
  string name = 1;
  // resource name of the customer that will checkout the book format "customers/{uuid}"
  string customer = 2;
}
message BooksCheckoutResponse {
  Loan loan = 1;
}

message BooksListRevisionsResponse {
  // Book revisions
  repeated BookRevision revisions = 1;
  // Next page token, used to fetch next page of revisions if results have more pages
  string next_page_token = 2;
}

//temporary because of resolution problems
message csgda {
  message core {
    message v1 {
      message AuditInfo {
        optional string user_id = 1;
        string client_id = 2;
        google.protobuf.Timestamp timestamp = 3;
      }
    }
  }
}