Rename "entities" to "records"

[jgaehring]

So while thinking more about #47, and ultimately in the course of replacing the stubs for #26, which involves restructuring how entities are handled and conceptualized in general, I've come back to this question which has been nagging me for a while...

Should I rename "entities" to "records" internally (ie, variable names, etc) and in the documentation for farmOS.js?

As deeply entrenched as this name is already (about 100 search matches or more, depending how you count, not to mention usage in Field Kit), I feel like this decision will become harder to reverse as it impacts more and more of the API surface.

I could really go the rabbit hole here in describing all the pros/cons of each approach, but I'll put a pin in it for now and continue using "entities" so I can wrap up #26, but the sooner I come back to this the better. It really ought to be before the beta release, and probably before I get too far with documentation as well (#22).

[mstenta]

My 2 cents: I think it makes sense to stick with "entities" for all internal and public APIs for consistency.

I went with "records" in the data model docs because I thought that would be a little easier to grok from a layman's standpoint, which is really the target audience of the data model docs.

We use "entities" in all farmOS APIs and documentation, and I believe farmOS.py does the same (is that right @paul121?) So for consistency I think it would make sense for farmOS.js to do the same.

Also easier than changing since that's what we have already haha. :-)

[jgaehring]

Very, very good points, @mstenta, thanks!

[paul121]

We use "entities" in all farmOS APIs and documentation, and I believe farmOS.py does the same (is that right @paul121?)

Yes, we use "entities" more than "records". But farmOS.py is really more coupled to the concept of JSON:API "resources".

Not trying to further complicate things, but I really think this makes the most sense for farmOS.py since that's what it is interacting with.. developers should understand that JSON:API resources is a layer on top of drupal entities. Maybe "records" is something that comes within the context of the application that implements farmOS.py/farmOS.js (like FK) ?

For example:

• The base class is called ResourceBase and methods have entity and bundle params: https://github.com/farmOS/farmOS.py/blob/ed88036ac0bc61fa100616f349fbdd484df4af0d/farmOS/client_2.py#L14
• Documentation references the same resource, entity and bundle terms: https://github.com/farmOS/farmOS.py/blob/1.x/docs/client_2x.md#resources

Each of these methods requires the JSON:API resource type identifier in order to determine the correct URL of the resource. Because the Drupal JSON:API module implements JSON:API resources in the format {entity_type}--{bundle}, the resource type identifier is supplied to each method with two arguments: entity_type and bundle.