Booleans without Prefixes

[nateklaiber]

I often include hints in resource objects. Things like has_items or is_owner etc. This is used as a hint and clear way to get an answer without having to directly look at associated resources (collection or instance).

The documentation states

Boolean properties SHOULD NOT use is, has, or another prefix.

And yet, if I want to relay those items as actual objects, then items or owner conflicts with those as objects.

In fact, the documentation does not propose how to handle this. It shoes a noun as incorrect ('item'), but then the correct has things like 'active', 'clever', and 'enabled'.

I believe without the prefix the intent is not clear. What is the recommendation in situations above?

[ca0abinary]

@nateklaiber Does it make sense in your scenario to use these guidelines to improve the usefulness of the data communicated? For example: has_items is good information, but maybe something like childItemCount would convey not only that there are child items but how many there are enabling enhanced decision making without querying the child items. In the case of is_owner / owner, it's not clear to me what that means and how there would be two instances of the owner property. Maybe the property names could get away with some disambiguation?

[nateklaiber]

@ca0abinary - very good points. I tend to include them both in different scenarios. Counter caches are important. Query methods are important.

I include counter caches where necessary (and move to a summary table if there are scoped counter caches).

I include query methods as helpful hints. A peek-ahead into the modeling without having to ask the modeling. I do this in server side code as well. I may have things like:

record.items?
record.hasItems()
record.items_count
record.itemsCount()
record.items
record.items()

Various approaches for different languages and support.

In a server side language, asking if record.items? then 'do something' else 'do something else' end is preferred over if record.items_count > 0 then 'do something' else 'do something else' end

My goal in including both is to not bind them together, but also let them serve their purposes.

Here's another example for an instance. In this case I have a 'has one' relationship on my resource. Having something like:

document.has_asset

Makes more sense to me than:

document.asset_count

Which will always be 0 or 1.

Again, I treat this as a query method related to the various associations. I find representing them in the API with these prefixes is helpful.

[ca0abinary]

@nateklaiber Thanks for a great explanation! I wonder if you can "have your cake and eat it too" here by providing for the additional features on the client side.

For example:

Server API provides a single integer value:

record.itemCount

Where the client implementation expands on that (pseudo-code alert):

ClientRecord
{
    List<ServerItemRecord> _items = null;
    List<ServerItemRecord> items = ServerRecord.itemCount > 0 ? getItemsFromCache() : null;
    boolean hasItems = () => ServerRecord.itemCount > 0;
    int items_count = ServerRecord.itemCount;
    int itemsCount = () => ServerRecord.itemCount;
    ...
}

In this example all the convenience functions are implemented client-side (be that a server client or user client) and can key off of one server side count.

Hopefully I'm understanding your ask correctly. 😄

[travisgosselin]

Including convenience properties in the API contract is nice, and maybe completely a benefit in some cases. In other cases, it serves to make contract design a bit uglier over time as that contract evolves. More importantly, though, I think as @ca0abinary is showing, the convenience functions you are looking for are automatically available in most languages.... serverRecord.Items.Any() (C#), serverRecord.items.isEmpty() (Java), _(serverRecord.items).isEmpty() (JavaScript). Additionally, you could include these functions as first-class properties of your model to have them available in the client SDK / HTTP Wrapper.

[nateklaiber]

Thanks for the response @travisgosselin 👍

I agree with you on contract design and it getting uglier. I think that's also a bigger and separate topic, as it has more to do with modeling the architecture at the gateway of your API as your systems evolve. This includes many other topics, too.

I do understand they're available in other languages. I use them often. I mostly spend time writing in Ruby, Python, and JavaScript as my top 3.

I also like to address separation between SDKs and the general client.

I still keep things like this in my server modeling:

def items?
  self.items.any?
end

def item?
  self.item.present?
end

This way I'm not conflating the concept of counter caches with presence in an instance or collection. Yes, they may be related, but I don't bind them as such and create the query method instead (or, in other languages I add the prefix to differentiate like record.items() and record.hasItems() - where one is a boolean check, and the other is the association).

I also often use jq on the command line, or another HTTP editor where I interact via curl or other tool. In that case it is easy to query where I can check a boolean response than the counter cache. In this case, there is no SDK around it yet. It's simply discovery or quick querying of the API.

Anyway, you've given me more food for thought, but my thought here is I still want to keep separation of concerns between what it means to 'have items' and 'items count' - and not bind them together (even though it may always be the case they are related in some fashion).

Thanks for the discussion.

[travisgosselin]

@nateklaiber - great question. I too have often used these types of prefixes in the past in some APIs I have built. In putting together these standards with our working group, and looking for consistency of usage in our terminology, we found that usage of such prefixes often were shortcuts to more fundamental questions we should be asking about our API contract.

If wanting a field like "is_owner", it's often a bit ambiguous in terms of what this owner is (obviously context is important and difficult to talk about in examples without some). If not including the actual "owner" complex object, then including a property name in the contract that more fundamentally describes the owner is encouraged. This should take place with an adjective (something that describes it). You might include an adjective to the "owner" noun (an adjective modifier) to do that effectively: "active_owner" if needed.

In terms of convenience properties for collections, the intent is that SDKs or language collection syntax is a preferred location to handle that.

[ca0abinary]

@nateklaiber Thanks for the example! I'm wondering if in a 1:1 scenario if it might be helpful to have the asset id. If that's null / undefined (javascript) then there is no related asset (due to lack of asset, storage issues, etc.) otherwise the id indicates an intact asset can be used as part of a later request for that specific asset.

Where I'm a little lost is it seems like is_owner could indicate ownership of multiple assets without clearly defining which. Is that a correct understanding? If so, as a developer I would expect receiptId to be defined or not and operate on that reference (and any other asset types would have a specific identifier as well).

[travisgosselin]

@nateklaiber If you have an Open API spec you wanted to share with the above-mentioned scenario, might make it easier to discuss/clarify?

[nateklaiber]

@ca0abinary @travisgosselin - I think it's important to find our common root for the discussion. I wanted to confirm that we're in agreement on most topics here. More on that shortly. Also, many things I'm referencing here are in private APIs that I'm not at liberty to share anything (But, I will work up some real world examples that we can all share and review).

I wanted to address the point of asset_id. For many of my resources I won't expose the ID for a has one relationship. You can only get it through /receipts/{id}/asset. I don't provide it as a standalone resource. So there is no asset_id or asset_count in these cases. However, we still want to be able to provide the client with the knowledge that there is indeed an asset at the other end (and it exists in storage without issues). This is by design. I don't want you to store or have reference to an ID in these cases. If you need to update the asset, you must do it through that endpoint, and the logic behind the scenes may handle paranoid deletes, versions, or time series. The point of entry is always through the parent resource. You also can't POST to something like /receipts/{id}/assets to create a new asset. It's a singular resource.

[nateklaiber]

As another example, the SPS Commerce API Documentation for Shipping Labels has an attribute of canRender. What approach would you take to remove this prefix? Or is can_ an acceptable prefix? Isn't this a boolean prefix? Without this prefix it would be render, correct? How would a developer interpret this?

[travisgosselin]

RE: Private APIs / Endpoints - sure, we have many internal APIs as well right now we don't expose. Sometimes when working in public forums we produce a smaller API spec as an example demonstration that is not exactly related to the original - but like you say, sometimes you can even lose context in these.

RE:asset_id - feels like you have structured this well based on the scenario from what I understand. If a resource does not require its own endpoint then don't expose it (don't expose anything you don't need too)... always not exposing an ID if its not required is a huge advantage as you evolve that API. This is the same spirit of reason for this line item:

Resource identifiers SHOULD NOT be serialized as numbers or integers (of any precision) as they should be considered opaque values to the API consumer.

https://spscommerce.github.io/sps-api-standards/standards/serialization.html#number

RE: canRender - As you have already seen, our public APIs do not yet follow these API Standards. Our biggest transformations right now are happening internally. For this specific scenario of canRender I would consider joining the verb render with an adjective like "availableRendering" or "renderingAvailable"... or "render" might be the wrong term entirely to use here if there is something more specific or a type of rendering. Its worth noting as well that this item in the API Standards is a SHOULD leaving some room for context specific decisions on best terminology in the domain. If a team was really adamant on using "canRender", that may be just fine.

[JamesStauffer]

We have an API with a has_views property that is manually kept in sync with the DB to tell the code if it should even query for views. Comments?

[travisgosselin]

This sounds like the REST endpoint is formulated to represent a database table or object rather than modeling a resource. I'd start by investigating what the resource would be and decoupling it from database concepts. At that point, perhaps a more "adjective" friendly name will materialize to represent what the views are describing in this case.

[JamesStauffer]

I'm drawing a blank trying to think of a good adjective friendly name. "viewable" would be too confusing.