crate names for services

[ctaggart]

service name

I've been hoping to derive the service name from the Python package-name or output-folder. The package-name was looking like a better option, but let's review a couple of examples. In #34, two of our Rust sdk packages here were named azure_cosmos and azure_service_bus.

https://github.com/Azure/azure-rest-api-specs/blob/master/specification/cosmos-db/resource-manager/readme.python.md
package-name: azure-mgmt-cosmosdb
output-folder: $(python-sdks-folder)/cosmos/azure-mgmt-cosmosdb/azure/mgmt/cosmosdb

https://github.com/Azure/azure-rest-api-specs/blob/master/specification/cosmos-db/data-plane/readme.python.md
package-name: azure-table
output-folder: "$(python-sdks-folder)/sdk/cosmos/azure-cosmos-table/azure/table/_generated"

https://github.com/Azure/azure-rest-api-specs/blob/master/specification/servicebus/resource-manager/readme.md
package-name: azure-mgmt-servicebus
output-folder: $(python-sdks-folder)/servicebus/azure-mgmt-servicebus/azure/mgmt/servicebus

https://github.com/Azure/azure-rest-api-specs/blob/master/specification/storage/resource-manager/readme.python.md
package-name: azure-mgmt-storage
output-folder: $(python-sdks-folder)/storage/azure-mgmt-storage/azure/mgmt/storage/

After going through this, I think it is best to not rely on another SDK, but use the specification folder name with a map to rename those that we want to. In this case specification/cosmos-db would automatically map to cosmos_db, but we could have an entry to map it to cosmos instead. For specification/servicebus, we could add entry to map it to service_bus.

package name

We need to come up with naming for Azure control plane and data plane. "control plane" aka "resource-manager". In #31, I had the control plane crate name as azure_mgmt_${service}, then changed it to azure_mgmt_${service}, but now think it would be better to change it back. The .NET package name is Microsoft.Azure.Management.CosmosDB were Management comes before the service name. It is easy to query for all management packages in the NuGet Gallery. Similarly, the python package name is azure-mgmt-cosmosdb. What should our Rust control plane package be named:

• azure_mgmt_cosmosdb
• azure_mgmt_cosmos
• azure_mgmt_cosmos_db
• azure_cosmosdb_mgmt
• azure_cosmos_mgmt
• azure_cosmos_db_mgmt

For the data plane, I'm not really sure what to do yet. If we use azure_mgmt_ or azure_management_ as a prefix for the control plane, it would be nice to use a prefix like azure_data_, azure_svc_, or azure_service_ for the data plane. As an example, let's look at the Azure Data Lake Storage. First, let's look at the URL from marketing:
https://azure.microsoft.com/en-us/services/storage/data-lake-storage/
And actually, if we look at the marketing service name for "Azure Cosmos DB":
https://azure.microsoft.com/en-us/services/cosmos-db/

Here are the package names for Azure Data Lake Strorage data plane:
https://github.com/Azure/azure-rest-api-specs/blob/master/specification/storage/data-plane/readme.md

• .NET: Microsoft.Azure.Storage.DataLake
• Python: azure-datalake-storage

What should the Rust data plane package name be?

• azure_datalake_storage
• azure_data_datalake_storage
• azure_svc_datalake_storage
• azure_service_datalake_storage
• azure_data_lake_storage
• azure_data_data_lake_storage
• azure_svc_data_lake_storage
• azure_service_data_lake_storage

Are crate names limited to 64 chars? That is a lot of characters, but may be something to keep in mind.
rust-lang/crates.io#718

[ctaggart]

In #31, I've moved forward with azure_mgmt_${service} where ${service} defaults to the snake_case of the spec directory name at https://github.com/Azure/azure-rest-api-specs/tree/master/specification . The service names can be set by adding an entry to:

const SERVICE_NAMES: &[(&str, &str)] = &[("cosmos-db", "cosmos"), ("vmware", "avs")];

It is a map from the spec directory name to the service name we wish to use. We just add an entry and do a git mv to the current code to rename a service.

For the data plane APIs, I'm currently planning to use azure_svc_${service}.

[rylev]

This does bring up the point of whether we're fitting a bit too much against ther grain by not using the names used in the spec directory. While cosmos-db to cosmos is not that big of a jump, vmware to avs is. Are we sure that the names we've chosen are better than the ones in the spec folder?

[ctaggart]

Naming is hard, which is why I created a private spreadsheet. We can look at the other SDKs, the REST API, & the product name to see what they used as well. I do think we should name it cosmos_db. I helped make AVS and the SDKs for it. We can use it as an example.

The REST API and the SDKs all use AVS:

• https://docs.microsoft.com/en-us/rest/api/avs/
• Python: azure.mgmt.avs
• C#: Microsoft.Azure.Management.Avs

The product service page, docs, and az cli extension all use vmware:

• https://azure.microsoft.com/en-us/services/azure-vmware/
• https://docs.microsoft.com/en-us/azure/azure-vmware/
• https://github.com/Azure/az-vmware-cli

So yes, pretty unclear. Given that the SDKs are for accessing the REST APIs, we should lean towards its naming as well as other SDKs.

[ctaggart]

This does bring up the point of whether we're fitting a bit too much against the grain by not using the names used in the spec directory.

I'm fine with just using the names used in the spec directory for the generated service crates.