Prefixing Internally Generated IDs with "sps" (i.e. spsOrgId)

[travisgosselin]

From @acchristensen:

So, my hypothesis. SPS will have its own identifiers for many different object types (Orgs, Items, Locations, Documents, etc).

1. It would be great if these had a common look and feel. Both in terms of naming and in terms of their structure (Org ID seems to be a generally good structure in terms of length, separation from implementation, and consistency).
2. OrgId (and others) aren't just an internal identifier. They are controlled by SPS, but they are shared (or will) to external API consumers. Therefore, our IDs should be identifiable as SPS identifiers to non-SPS "folks".
3. Our business, by its nature, means that we are translating identifiers between multiple parties with their own look and feels for their identifiers. So, building on option 2, we should make an effort to ensure that our identifiers are described in a way that ensures they are not confused with other parties and that it was SPS that provided and controls that field and its value.
4. This is not related to the naming of the field, but its contents. I posit that the values of our identifiers should be "self-describing" so that even if the field name is lost it is clear both where the identifier came from and to what type of object it is referring to.

So, putting that all together, I think it makes a lot of sense for us to always call out that a given field is provided by SPS and to aid in making it relatable to SPS.

[lehn0058]

I’ve been thinking through this one a lot lately for the Item API, and I have several concerns with this approach.

Prefixing ids is easy enough for an org that is pretty well defined and unique across the entire SPS ecosystem. BUT there are a LOT of internal SPS ids. Just doing it for a domain (Item, Org, Location, Document, etc) may make sense. BUT each table in a database has an internal identifier. And from this proposal each table id returned would require a prefix. Our Attribute Registry schema only contains metadata about how items are described (not even item data itself) would have 25 different id prefixes we would need to account for. Many of these (valid, value, group, datatype, comment, etc) would likely have collisions with other prefixes other teams would create. I am worried we are setting ourselves up to confuse the user more by using this method and likely a headache for ourselves trying to assure ids are unique and the prefix is intelligible.

I’m also not quite following where the concern is coming from regarding having an id but not knowing what it is. I can’t think of a time I had an id and not known what it was in the context for the API (usually I have the object with the id assigned via its parameter or have a variable containing them with a name describing what it is). Is this an issue particular to a certain area within SPS (XREF perhaps)? Wondering if we are solving a particular domains problem and it is leaking out to all other domains.

[travisgosselin]

I appreciate the sentiment as well that adding "sps" as a prefix to everything may seem like "overkill" to do across ALL DOMAINS.

However, I'm not sure I understand why a modification to the API contract would have bearing on the DB implementation or field mapping. I understand if your using an ORM or liking a straight pass-through for mapping simplicity, but I expect in reality moving forward with an API-First approach, that a mapping layer will be needed more than ever for applications to conform to standards contracts (i.e. separating boundaries of your API model from you DB model through separate DTO objects is always helpful, even when at first it may seem like a 1-1 wasted effort).

[lehn0058]

For sure the API response won't map 1-to-1 to a backend data model. But there are simple use cases where there are still a large number of ids that could come back. Lets use comments as an example. Since comments likely exist in many places, how do we ensure id prefixes are unique? spsComment would likely want to be used in many different domains. Should it be prefixed by the domain it is in somehow? For the org example, perhaps something like spsOrgComment? That could chain a little long, but trying to think through how to keep the prefixes actually unique.

[acchristensen]

I believe the base need is to provide clarity that an identifier for a business domain object that is "shared" between trading partners is properly contextualized to the system it relates to. Does that mean adding sps to EVERY object? The only reason I can think to do that is for consistency. Business Domain Objects like Item, Location, Company, Document that will have identifiers within the Systems that are integrating with our APIs that especially could be easily confused between SPS' and the Trading Partners IDs are the ones I'm thinking need to be contextualized. If something is more of, in a UML sense, an aggregate (it can't exist without its containing object) I don't see a need there (again, other than consistency). Just to help clarify why I see this as important.
FWIW, this is not a special pattern I came up with. It's seen in comparative markets, as well. Here's an example from DSCO: https://api.dsco.io/doc/v3/reference/#operation/getCatalogById See the itemKey. It's more of a qualifier-style, but dscoItemId is one of the item key types.

[travisgosselin]

I think I can agree that this might make a lot of sense on some particular domain-specific IDs that we would identify, as you suggested with some examples. Wondering if this materializes only when paired with the new cross-domain ID representation formats (like spsItemId) that you are working on....

[acchristensen]

That could be an interesting "test" as to when we'd want these. Like, if the business domain object is reusable and reference-able, standalone, across multiple APIs or other domains. Or maybe just if it is important enough to create a swaggerhub domain for?

[acchristensen]

The concern around identifying objects returned from the API outside the context of the API can come up in different ways. But it's usually going to be troubleshooting. Viewing logs would be one scenario. Or copy/pasting the API response to an email (to send to our support, to share within a company, etc). Or even in an ETL scenario where a customer has dumped the output of SPS API calls to be post-processed by some other systems.

[travisgosselin]

The work done around URN-like references should provide and answer the need here: https://github.com/SPSCommerce/sps-api-standards/releases/tag/v1.3.0