Straighten out "id", "key", and "slug"

[kdmccormick]

Working with Learning Core's authoring api is mostly a joy, except for the inconsistent usage of the terms "id", "key", and "slug". This applies to the LC-related objects and models in opaque-keys and edx-platform, as well.

I would propose standardizing on these meanings of each term for all new content-related code, and for any existing code which is not too burdensome to change:

• *_id is an integer primary key.
• *_uuid is a UUID.
• *_slug is a URL-friendly string which identifies something within a local scope. On the Component model, we currently call this is a "local key".
• *_key is a string (or an opaque-keys object) which uniquely identifies something across a whole Open edX instance. Can be composed of slugs, or of other slug-like things like a block/component type.

For example, one change I'd like to make is:

• On the model, Collection.key should be renamed Collection.slug
• The corresponding field on the opaque-keys object, LibraryCollectionLoctator.collection_id should be renamed LibraryCollectionLocator.slug.
• Function arguments and dataclass members should be renamed accordingly.

[ormsbee]

I actually don't think we should be storing site-global identifiers within a LearningPackage at all, since that content could be moved to a different instance entirely. My initial thought was that all key/slug-like identifiers would be local, and that instance-unique identifiers would be derived from them. I'm actually coming to think that even assuming UUIDs would be globally unique was a mistake on my part.

[kdmccormick]

I actually don't think we should be storing site-global identifiers within a LearningPackage at all, since that content could be moved to a different instance entirely.

This makes sense.

My initial thought was that all key/slug-like identifiers would be local, and that instance-unique identifiers would be derived from them

I agree, but calling them "keys" seems confusing to me. The most common use of Learning Core will be as a backend for edx-platform learning content, which almost always uses "key" to mean a global identifier for a learning context or a usage. I found myself tripping over this while developing the Import API. If it weren't for the type hints, it would have been very challenging to keep straight.

[kdmccormick]

I'm actually coming to think that even assuming UUIDs would be globally unique was a mistake on my part.

Interesting. Just trying to understand this-- is this because we'd want to be able to entirely duplicate the entities of one LP into a new LP without worrying about conflicting identifiers, which would work with the keys/slugs but break with uuids?

Are we using the UUIDs at all? If not, and if we see no clear use for them, I wonder if it would make sense to remove them before anyone depends on them.

[bradenmacdonald]

I've generally not used the UUIDs at all, and they seem kind of redundant given we have integer primary keys for intra-Learning Core relationships, and tend to use high-level keys (opaque keys) based on key/slug for everything else.

[bradenmacdonald]

Also worth noting that in the REST APIs I've generally tended to use only the opaque key, but call it id because some frontend tooling expects / only works when you have a field called id.

See https://github.com/openedx/edx-platform/blob/3651b74738012686a66c311d82d65b5c8d4354d6/openedx/core/djangoapps/content_libraries/rest_api/serializers.py#L34-L39 for example.

We usually define a "write-only" field called slug that can be used to set the slug/key on creation, but is not used when reading objects back from the API.

We also have an old TODO here to rename a legacy definition_id field from the blockstore era to slug: https://github.com/openedx/edx-platform/blob/3651b74738012686a66c311d82d65b5c8d4354d6/openedx/core/djangoapps/content_libraries/rest_api/serializers.py#L196-L204

The REST API also has an inconsistency with collections that I didn't catch in time. While the other objects (blocks, containers, etc.) all use opaque keys in their REST API URLs, e.g. /api/xblock/v2/xblocks/lb:BradenX:LC1:problem:example-prolem@draft/fields/ for an XBlock, the Collections API uses a pair of key and the library opaque key, e.g. /api/libraries/v2/lib:BradenX:LC1/collections/basic-collection/. This is despite us having a LibraryCollectionLocator that we could be using to be similar to all the other library APIs.