Variability between property name prefixing

[lehn0058]

I'm wanting to discuss property naming mentioned in the following section: https://atlassian.spscommerce.com/wiki/display/SIP/API+-+Naming#APINaming-PropertyNames

It mentions rules for when to prefix property names vs when not too. Below is an example:

// INCORRECT EXAMPLE
GET /v1/books/2345
RESPONSE
{
    "bookId": 2345,                             // since the request for the resource was a "book", the attribute should just be "id"
    "name": "The Best Book",
    "author": {                    
        "authorId":456,                         // the parent entity is an author, so it should be "id" for the attribute name.
        "authorName": "John Doe",               // the parent entity is an author, so it should be "name" for the attribute name.
        "publisherName": "My Publishing House"  // this name attribute MUST have a prefix for another entity, since its not the name of this entity "author"
        "agentId": 2                            // this name is appropriate with Id following its associated entity name.
    }
}
 
// CORRECT EXAMPLE
GET /v1/books/2345
RESPONSE
{
    "id": 2345,                            
    "name": "The Best Book",
    "author": {                    
        "id":456,                      
        "name": "John Doe",            
        "publisherName": "My Publishing House",
        "agentId": 2
    }
}

While this does make the API response look cleaner, I've often experienced that this causes more confusion for the users of the API, in particular for the unique identifier (id in this case). For example, if we were comparing two objects with a foreign key pointing to each other:

const item = {
    id: 2345,                            
    name: "my cool name",
}

const thing = {
   id: 7890,
   bookId: 2345,
   count: 20
}

In this example, I have no idea looking at the spec what object types item or thing is. If we are doing an equality and if we know that we have a foreign key reference between the two objects (no guarantee from the schema though), looking at the data this example maybe indicates that we should do:

item.id == thing.bookId

But when in our code editor we often are not looking at the JSON data. We are looking at the properties on the response object for the spec we are given or the object types we have. It is much more clear if the primary identifiers had been fully prefixed out and the properties of both objects match:

const item = {
    bookId: 2345,                            
    name: "my cool name",
}

const thing = {
   publisherId: 7890,
   bookId: 2345,
   count: 20
}

Even though item may still not be a book (thing has multiple ids after all) there is still much less confusion about whether we are doing the correct equality comparison:

item.bookId == thing.bookId

[travisgosselin]

The goal of the existing standards was to provide consistent naming on properties and what they are associated to for not just IDs but for all property types. Are you advocating that "id" is an exception to that rule only? or that ALL properties should have prefixes?

I think I prefer that consistency on all properties without the prefix on any, than having an exception for id. I cannot say I have experienced the confusion you have in other APIs that have taken this approach. Even in your example when using item.id that is obvious to me that it is the id of the object (item). If the variable was poorly named... obviously thats a different issue.

Looking at some of our reference APIs, i.e. GitHub API as a good place to start, as its developer experience rep is usually pretty high, their endpoints follow the existing pattern specified in the standards (i.e. using ID).
https://docs.github.com/en/rest/reference/

[acchristensen]

Gr. Yeah, it's a good point since we're focusing on the clarity of the spec.
One convention we do see sometimes is to specially annotate a json field with a $ or @ prefix. So we could do something like @spsItemId to indicate that the ID of this is that particular attribute. But... that feels a little esoteric :-/

[travisgosselin]

Agreed - I think adding "sps" as a prefix likely captures all "@" or symbol advantages and then some. I'd like to reserve symbol prefixes for potential usage in REST specific semantics (generically) in the future as well (not sure how, just thinking long term out loud).

[acchristensen]

Well, except the sps prefix could be for multiple identifiers in the body. So, it could both be a prefix of an identifier of this, but then also be the prefix of identifiers of any referenced objects.

[travisgosselin]

@lehn0058 - just following up on the discussion - do you feel like this one has come to a sufficient answer? Leaving the standards as is? Or want to leave the discussion open for further analysis?

[lehn0058]

I feel like we have a workaround (let the clients override if they decide to), but I don't really feel like we have a solution to this issue. That said, I'm not sure this is an easy one to solve for... most specs probably go the route of "this is what most other ones are doing" which is why I have run into this issue with so many of them. If so many others have not been able to solve it though, I'm not confident we will be able to without significant investment, and that doesn't really feel worth it for something like this. I am ok with closing out this discussion.