feat: allow users to specify shipment resource ID

This makes the API more declarative and adherant to the following AIP:
https://google.aip.dev/122#resource-id-segments

openapiv2/book.swagger.yaml

@@ -256,7 +256,10 @@ paths:
             $ref: '#/definitions/rpcStatus'
       parameters:
         - name: shipment
-          description: The resource name of the shipment to retrieve.
+          description: |-
+            The resource name of the shipment to retrieve.
+            Format:
+            `spaces/{space}/shipments{shipment_id}`
           in: path
           required: true
           type: string
@@ -313,7 +316,10 @@ paths:
             $ref: '#/definitions/rpcStatus'
       parameters:
         - name: shipment
-          description: The resource name of the shipment to cancel.
+          description: |-
+            The resource name of the shipment to cancel.
+            Format:
+            `spaces/{space}/shipments{shipment_id}`
           in: path
           required: true
           type: string
@@ -345,7 +351,10 @@ paths:
             $ref: '#/definitions/rpcStatus'
       parameters:
         - name: shipment
-          description: The resource name of the shipment to release.
+          description: |-
+            The resource name of the shipment to release.
+            Format:
+            `spaces/{space}/shipments{shipment_id}`
           in: path
           required: true
           type: string
@@ -399,7 +408,10 @@ paths:
             $ref: '#/definitions/rpcStatus'
       parameters:
         - name: space
-          description: The parent space in which to create the shipment.
+          description: |-
+            The parent Saga Space in which to create the shipment.
+            Format:
+            `spaces/{space}`
           in: path
           required: true
           type: string
@@ -412,6 +424,20 @@ paths:
             $ref: '#/definitions/v1beta1Shipment'
             required:
               - shipment
+        - name: shipmentId
+          description: |-
+            A user specified ID for the shipment resource. This must adhere to these rules:
+              1. Must be unique within a space, including soft-deleted and cancelled shipments.
+              2. Must only contain upper-case letters, lower-case letters, numbers 0-9 and a hyphen '-'.
+              3. Must have a length between 4 and 63 characters.
+              4. Must start with a letter or a number.
+              5. Must end with a letter or a number.
+            The following regular expression can be used to validate these rules:
+              ^[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$
+            If no value is provided then an ID will be generated.
+          in: query
+          required: false
+          type: string
       tags:
         - ShipmentService
   /v1beta1/{space}/tours:
@@ -430,7 +456,10 @@ paths:
             $ref: '#/definitions/rpcStatus'
       parameters:
         - name: space
-          description: The parent space in which to create the tour.
+          description: |-
+            The parent space in which to create the tour.
+            Format:
+            `spaces/{space}`
           in: path
           required: true
           type: string
@@ -565,7 +594,10 @@ paths:
             $ref: '#/definitions/rpcStatus'
       parameters:
         - name: tour
-          description: The resource name of the tour to retrieve.
+          description: |-
+            The resource name of the tour to retrieve.
+            Format:
+            `spaces/{space}/tours/{tour_id}`
           in: path
           required: true
           type: string
@@ -590,7 +622,10 @@ paths:
             $ref: '#/definitions/rpcStatus'
       parameters:
         - name: tour
-          description: The resource name of the tour to confirm.
+          description: |-
+            The resource name of the tour to confirm.
+            Format:
+            `spaces/{space}/tours/{tour_id}`
           in: path
           required: true
           type: string

proto/einride/saga/extend/book/v1beta1/booking_service.proto

@@ -86,6 +86,8 @@ service BookingService {
 // The request message to create a tour.
 message CreateTourRequest {
   // The parent space in which to create the tour.
+  // Format:
+  // `spaces/{space}`
   string parent = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {type: "api.saga.einride.tech/Space"},
@@ -101,6 +103,8 @@ message CreateTourRequest {
 // The request message to get a tour.
 message GetTourRequest {
   // The resource name of the tour to retrieve.
+  // Format:
+  // `spaces/{space}/tours/{tour_id}`
   string name = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {type: "api.saga.einride.tech/Tour"},
@@ -113,6 +117,8 @@ message GetTourRequest {
 // The request message to confirm a tour.
 message ConfirmTourRequest {
   // The resource name of the tour to confirm.
+  // Format:
+  // `spaces/{space}/tours/{tour_id}`
   string name = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {type: "api.saga.einride.tech/Tour"},

proto/einride/saga/extend/book/v1beta1/shipment_service.proto

@@ -127,7 +127,7 @@ service ShipmentService {
       post: "/v1beta1/{parent=spaces/*}/shipments"
       body: "shipment"
     };
-    option (google.api.method_signature) = "parent,shipment";
+    option (google.api.method_signature) = "parent,shipment,shipment_id";
     option (einride.iam.v1.method_authorization) = {
       permission: "book.shipments.create"
       before: {
@@ -213,7 +213,9 @@ service ShipmentService {
 
 // Request message for BookService.CreateShipment.
 message CreateShipmentRequest {
-  // The parent space in which to create the shipment.
+  // The parent Saga Space in which to create the shipment.
+  // Format:
+  // `spaces/{space}`
   string parent = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {type: "api.saga.einride.tech/Space"},
@@ -222,13 +224,26 @@ message CreateShipmentRequest {
     }
   ];
 
+  // A user specified ID for the shipment resource. This must adhere to these rules:
+  //   1. Must be unique within a space, including soft-deleted and cancelled shipments.
+  //   2. Must only contain upper-case letters, lower-case letters, numbers 0-9 and a hyphen '-'.
+  //   3. Must have a length between 4 and 63 characters.
+  //   4. Must start with a letter or a number.
+  //   5. Must end with a letter or a number.
+  // The following regular expression can be used to validate these rules:
+  //   ^[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$
+  // If no value is provided then an ID will be generated.
+  string shipment_id = 3 [(google.api.field_behavior) = OPTIONAL];
+
   // The shipment to create.
   Shipment shipment = 2 [(google.api.field_behavior) = REQUIRED];
 }
 
 // Request message for BookService.GetShipment.
 message GetShipmentRequest {
   // The resource name of the shipment to retrieve.
+  // Format:
+  // `spaces/{space}/shipments{shipment_id}`
   string name = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {type: "api.saga.einride.tech/Shipment"},
@@ -241,6 +256,8 @@ message GetShipmentRequest {
 // Request message for BookService.ReleaseShipment.
 message ReleaseShipmentRequest {
   // The resource name of the shipment to release.
+  // Format:
+  // `spaces/{space}/shipments{shipment_id}`
   string name = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {type: "api.saga.einride.tech/Shipment"},
@@ -253,6 +270,8 @@ message ReleaseShipmentRequest {
 // Request message for BookService.CancelShipment.
 message CancelShipmentRequest {
   // The resource name of the shipment to cancel.
+  // Format:
+  // `spaces/{space}/shipments{shipment_id}`
   string name = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {type: "api.saga.einride.tech/Shipment"},