Download api breaking improvements

README.md

@@ -4,13 +4,13 @@ Copyright 2025 Logan Magee
 SPDX-License-Identifier: MPL-2.0
 -->
 
-# Accrescent Directory API
+# Accrescent App Store API
 
-The Accrescent directory API definitions.
+The Accrescent app store API definitions.
 
 ## About
 
-The directory API is the gRPC API used by Accrescent clients to retrieve information about apps
+The app store API is the gRPC API used by Accrescent clients to retrieve information about apps
 available in the store. Specifically, it allows clients to:
 
 - List apps available for installation in the store
@@ -20,7 +20,7 @@ available in the store. Specifically, it allows clients to:
 - Determine whether an app is compatible with a device
 - ...and more
 
-API definitions are published to [Buf] at the [directory API BSR repository], which also generates
+API definitions are published to [Buf] at the [app store API BSR repository], which also generates
 client SDKs.
 
 ## Versioning policy
@@ -32,6 +32,6 @@ Semantic Versioning rules; however, server implementers may experience breaking
 versions.
 
 [Buf]: https://buf.build
-[Buf-generated SDKs]: https://buf.build/accrescent/directory-api/sdks
-[directory API BSR repository]: https://buf.build/accrescent/directory-api
+[Buf-generated SDKs]: https://buf.build/accrescent/appstore-api/sdks
+[app store API BSR repository]: https://buf.build/accrescent/appstore-api
 [semantic versioning]: https://semver.org

accrescent/directory/v1/app_download_info.proto → accrescent/appstore/v1/app_download_info.proto

@@ -4,20 +4,16 @@
 
 syntax = "proto3";
 
-package accrescent.directory.v1;
+package accrescent.appstore.v1;
 
-import "accrescent/directory/v1/package_info.proto";
-import "accrescent/directory/v1/split_download_info.proto";
+import "accrescent/appstore/v1/split_download_info.proto";
 import "buf/validate/validate.proto";
 
 option java_multiple_files = true;
-option java_package = "app.accrescent.directory.v1";
+option java_package = "app.accrescent.appstore.v1";
 
 // App download information for a given app.
 message AppDownloadInfo {
   // Download info for each individual split APK.
   repeated SplitDownloadInfo split_download_info = 1 [(buf.validate.field).repeated.min_items = 1];
-
-  // Package information for this app.
-  PackageInfo package_info = 2 [(buf.validate.field).required = true];
 }

accrescent/directory/v1/app_listing.proto → accrescent/appstore/v1/app_listing.proto

@@ -4,13 +4,13 @@
 
 syntax = "proto3";
 
-package accrescent.directory.v1;
+package accrescent.appstore.v1;
 
-import "accrescent/directory/v1/image.proto";
+import "accrescent/appstore/v1/image.proto";
 import "buf/validate/validate.proto";
 
 option java_multiple_files = true;
-option java_package = "app.accrescent.directory.v1";
+option java_package = "app.accrescent.appstore.v1";
 
 // A localized store listing for a given app.
 message AppListing {

accrescent/appstore/v1/app_service.proto

@@ -0,0 +1,60 @@
+// Copyright 2024 Logan Magee
+//
+// SPDX-License-Identifier: MPL-2.0
+
+syntax = "proto3";
+
+package accrescent.appstore.v1;
+
+import "accrescent/appstore/v1/get_app_download_info_request.proto";
+import "accrescent/appstore/v1/get_app_download_info_response.proto";
+import "accrescent/appstore/v1/get_app_listing_request.proto";
+import "accrescent/appstore/v1/get_app_listing_response.proto";
+import "accrescent/appstore/v1/get_app_package_info_request.proto";
+import "accrescent/appstore/v1/get_app_package_info_response.proto";
+import "accrescent/appstore/v1/get_app_update_info_request.proto";
+import "accrescent/appstore/v1/get_app_update_info_response.proto";
+import "accrescent/appstore/v1/list_app_listings_request.proto";
+import "accrescent/appstore/v1/list_app_listings_response.proto";
+
+option java_multiple_files = true;
+option java_package = "app.accrescent.appstore.v1";
+
+// Service providing RPCs for querying all Accrescent apps.
+service AppService {
+  // Retrieves a single app's listing.
+  //
+  // The following status codes have defined meanings:
+  //
+  // - INVALID_ARGUMENT: the request parameters are invalid
+  // - NOT_FOUND: an app with the provided ID could not be found
+  rpc GetAppListing(GetAppListingRequest) returns (GetAppListingResponse);
+
+  // Retrieves a list of unique app listings.
+  rpc ListAppListings(ListAppListingsRequest) returns (ListAppListingsResponse);
+
+  // Retrieves an app's package information.
+  //
+  // The following status codes have defined meanings:
+  //
+  // - INVALID_ARGUMENT: the request parameters are invalid
+  rpc GetAppPackageInfo(GetAppPackageInfoRequest) returns (GetAppPackageInfoResponse);
+
+  // Retrieves an app's download information.
+  //
+  // The following status codes have defined meanings:
+  //
+  // - INVALID_ARGUMENT: the request parameters are invalid
+  // - NOT_FOUND: an app with the provided ID could not be found
+  // - FAILED_PRECONDITION: the app is incompatible with the specified device
+  rpc GetAppDownloadInfo(GetAppDownloadInfoRequest) returns (GetAppDownloadInfoResponse);
+
+  // Retrieves an app's update information.
+  //
+  // The following status codes have defined meanings:
+  //
+  // - INVALID_ARGUMENT: the request parameters are invalid
+  // - NOT_FOUND: an app with the provided ID could not be found
+  // - FAILED_PRECONDITION: the app is incompatible with the specified device
+  rpc GetAppUpdateInfo(GetAppUpdateInfoRequest) returns (GetAppUpdateInfoResponse);
+}

accrescent/appstore/v1/app_update_info.proto

@@ -0,0 +1,19 @@
+// Copyright 2025 Logan Magee
+//
+// SPDX-License-Identifier: MPL-2.0
+
+syntax = "proto3";
+
+package accrescent.appstore.v1;
+
+import "accrescent/appstore/v1/split_update_info.proto";
+import "buf/validate/validate.proto";
+
+option java_multiple_files = true;
+option java_package = "app.accrescent.appstore.v1";
+
+// App update information for a given app.
+message AppUpdateInfo {
+  // Update info for each individual split APK.
+  repeated SplitUpdateInfo split_update_info = 1 [(buf.validate.field).repeated.min_items = 1];
+}

accrescent/directory/v1/device_attributes.proto → accrescent/appstore/v1/device_attributes.proto

@@ -4,13 +4,13 @@
 
 syntax = "proto3";
 
-package accrescent.directory.v1;
+package accrescent.appstore.v1;
 
 import "android/bundle/devices.proto";
 import "buf/validate/validate.proto";
 
 option java_multiple_files = true;
-option java_package = "app.accrescent.directory.v1";
+option java_package = "app.accrescent.appstore.v1";
 
 // A client device's hardware and OS attributes.
 message DeviceAttributes {

accrescent/directory/v1/get_app_download_info_request.proto → accrescent/appstore/v1/get_app_download_info_request.proto

@@ -4,13 +4,13 @@
 
 syntax = "proto3";
 
-package accrescent.directory.v1;
+package accrescent.appstore.v1;
 
-import "accrescent/directory/v1/device_attributes.proto";
+import "accrescent/appstore/v1/device_attributes.proto";
 import "buf/validate/validate.proto";
 
 option java_multiple_files = true;
-option java_package = "app.accrescent.directory.v1";
+option java_package = "app.accrescent.appstore.v1";
 
 // Request defining parameters for retrieving an app's download info.
 message GetAppDownloadInfoRequest {
@@ -35,9 +35,4 @@ message GetAppDownloadInfoRequest {
   // The current device's hardware and OS attributes used to determine app
   // compatibility, download size, etc.
   DeviceAttributes device_attributes = 2 [(buf.validate.field).required = true];
-
-  // The base version of the app to get download info from (almost always the
-  // currently installed version). If unspecified, indicates that this is an
-  // initial installation instead of an update.
-  optional uint64 base_version_code = 3 [(buf.validate.field).uint64.gt = 0];
 }

accrescent/appstore/v1/get_app_download_info_response.proto

@@ -0,0 +1,19 @@
+// Copyright 2024 Logan Magee
+//
+// SPDX-License-Identifier: MPL-2.0
+
+syntax = "proto3";
+
+package accrescent.appstore.v1;
+
+import "accrescent/appstore/v1/app_download_info.proto";
+import "buf/validate/validate.proto";
+
+option java_multiple_files = true;
+option java_package = "app.accrescent.appstore.v1";
+
+// Response to requesting an app's download info.
+message GetAppDownloadInfoResponse {
+  // The app's download info.
+  AppDownloadInfo app_download_info = 1 [(buf.validate.field).required = true];
+}

accrescent/directory/v1/get_app_listing_request.proto → accrescent/appstore/v1/get_app_listing_request.proto

@@ -4,12 +4,12 @@
 
 syntax = "proto3";
 
-package accrescent.directory.v1;
+package accrescent.appstore.v1;
 
 import "buf/validate/validate.proto";
 
 option java_multiple_files = true;
-option java_package = "app.accrescent.directory.v1";
+option java_package = "app.accrescent.appstore.v1";
 
 // Request defining parameters for retrieving an app listing.
 message GetAppListingRequest {

accrescent/directory/v1/get_app_listing_response.proto → accrescent/appstore/v1/get_app_listing_response.proto

@@ -4,13 +4,13 @@
 
 syntax = "proto3";
 
-package accrescent.directory.v1;
+package accrescent.appstore.v1;
 
-import "accrescent/directory/v1/app_listing.proto";
+import "accrescent/appstore/v1/app_listing.proto";
 import "buf/validate/validate.proto";
 
 option java_multiple_files = true;
-option java_package = "app.accrescent.directory.v1";
+option java_package = "app.accrescent.appstore.v1";
 
 // Response to requesting an app listing.
 message GetAppListingResponse {

accrescent/directory/v1/get_app_package_info_request.proto → accrescent/appstore/v1/get_app_package_info_request.proto

@@ -4,12 +4,12 @@
 
 syntax = "proto3";
 
-package accrescent.directory.v1;
+package accrescent.appstore.v1;
 
 import "buf/validate/validate.proto";
 
 option java_multiple_files = true;
-option java_package = "app.accrescent.directory.v1";
+option java_package = "app.accrescent.appstore.v1";
 
 // Request defining parameters for retrieving an app's package info.
 message GetAppPackageInfoRequest {

accrescent/directory/v1/get_app_package_info_response.proto → accrescent/appstore/v1/get_app_package_info_response.proto

@@ -4,13 +4,13 @@
 
 syntax = "proto3";
 
-package accrescent.directory.v1;
+package accrescent.appstore.v1;
 
-import "accrescent/directory/v1/package_info.proto";
+import "accrescent/appstore/v1/package_info.proto";
 import "buf/validate/validate.proto";
 
 option java_multiple_files = true;
-option java_package = "app.accrescent.directory.v1";
+option java_package = "app.accrescent.appstore.v1";
 
 // Response to requesting an app's package info.
 message GetAppPackageInfoResponse {

accrescent/appstore/v1/get_app_update_info_request.proto

@@ -0,0 +1,45 @@
+// Copyright 2025 Logan Magee
+//
+// SPDX-License-Identifier: MPL-2.0
+
+syntax = "proto3";
+
+package accrescent.appstore.v1;
+
+import "accrescent/appstore/v1/device_attributes.proto";
+import "buf/validate/validate.proto";
+
+option java_multiple_files = true;
+option java_package = "app.accrescent.appstore.v1";
+
+// Request defining parameters to retrieving an app's update info.
+message GetAppUpdateInfoRequest {
+  // The application ID of the update info to retrieve.
+  optional string app_id = 1 [
+    (buf.validate.field).required = true,
+    // According to
+    // https://developer.android.com/build/configure-app-module#set-application-id,
+    // the app ID must conform to the following rules:
+    //
+    // 1. It must have at least two segments (one or more dots).
+    // 2. Each segment must start with a letter.
+    // 3. All characters must be alphanumeric or an underscore [a-zA-Z0-9_].
+    //
+    // The maximum length is imposed by us to set a reasonable limit.
+    (buf.validate.field).string = {
+      pattern: "^([a-zA-Z][a-zA-Z0-9_]*\\.)+[a-zA-Z][a-zA-Z0-9_]*$"
+      max_bytes: 128
+    }
+  ];
+
+  // The current device's hardware and OS attributes used to determine app
+  // compatibility, download size, etc.
+  DeviceAttributes device_attributes = 2 [(buf.validate.field).required = true];
+
+  // The base version of the app to get update info from, i.e., the currently
+  // installed version.
+  optional uint64 base_version_code = 3 [
+    (buf.validate.field).required = true,
+    (buf.validate.field).uint64.gt = 0
+  ];
+}

accrescent/appstore/v1/get_app_update_info_response.proto

@@ -0,0 +1,18 @@
+// Copyright 2025 Logan Magee
+//
+// SPDX-License-Identifier: MPL-2.0
+
+syntax = "proto3";
+
+package accrescent.appstore.v1;
+
+import "accrescent/appstore/v1/app_update_info.proto";
+
+option java_multiple_files = true;
+option java_package = "app.accrescent.appstore.v1";
+
+// Response to requesting an app's update info.
+message GetAppUpdateInfoResponse {
+  // The app's update info. Present if and only if the app is not up-to-date.
+  AppUpdateInfo app_update_info = 1;
+}

accrescent/directory/v1/image.proto → accrescent/appstore/v1/image.proto

@@ -4,12 +4,12 @@
 
 syntax = "proto3";
 
-package accrescent.directory.v1;
+package accrescent.appstore.v1;
 
 import "buf/validate/validate.proto";
 
 option java_multiple_files = true;
-option java_package = "app.accrescent.directory.v1";
+option java_package = "app.accrescent.appstore.v1";
 
 // Graphical image to be displayed in client UI.
 message Image {

accrescent/directory/v1/list_app_listings_request.proto → accrescent/appstore/v1/list_app_listings_request.proto

@@ -4,10 +4,10 @@
 
 syntax = "proto3";
 
-package accrescent.directory.v1;
+package accrescent.appstore.v1;
 
 option java_multiple_files = true;
-option java_package = "app.accrescent.directory.v1";
+option java_package = "app.accrescent.appstore.v1";
 
 // Request defining parameters for retrieving multiple app listings.
 message ListAppListingsRequest {

accrescent/directory/v1/list_app_listings_response.proto → accrescent/appstore/v1/list_app_listings_response.proto

@@ -4,13 +4,13 @@
 
 syntax = "proto3";
 
-package accrescent.directory.v1;
+package accrescent.appstore.v1;
 
-import "accrescent/directory/v1/app_listing.proto";
+import "accrescent/appstore/v1/app_listing.proto";
 import "buf/validate/validate.proto";
 
 option java_multiple_files = true;
-option java_package = "app.accrescent.directory.v1";
+option java_package = "app.accrescent.appstore.v1";
 
 // Response to requesting a list of app listings.
 message ListAppListingsResponse {