search

aep-dev / aeps

AEPs help developers and organizations build clear, consistent network APIs and clients by providing an extensible set of design guidelines.
http://aep.dev/
Other
21 stars 15 forks source link

Proposal: use standard nouns instead of resource singular for field names standard patterns and methods. #205

Open toumorokoshi opened 3 months ago

toumorokoshi commented 3 months ago

This is spawned by https://github.com/aep-dev/aep.dev/pull/200/files#r1682253152.

Today aeps have a pattern of using the resource singular as a field name. For example, create is something like:

message CreateRequest {
    Book book = 1;
}

When these patterns leak into the more dynamic world of json, it makes it difficult to create simple, dynamic queries.

One example is the one linked above: with resource revisions, we could either call a revision 'snapshot' all the time, or we could use the resource singular:

message Revision {
    Book book; // option 1.
    Book snapshot // option 2.
}

For a json client, it'd be great to be able to extract all snapshots with a common jq query, something like:

curl 'http://www.example.com/book/my-book/revisons' | jq ".items[] | .snapshot"

This jq would not have to change if we called the field snapshot everywhere.

Ideally for standard methods and design patterns, we don't use the resource singular, instead reserving it for something like a resource reference instead.

rofrankel commented 3 months ago

Yeah this is definitely simpler in some ways, albeit maybe slightly uglier ("snapshot" doesn't bother me but, having to call the field in a create request "resource" does a bit).

We concluded we shouldn't optimize for this and I still agree with that conclusion, but FWIW, this change would make Roblox fully adopting AEPs a bit more challenging, since we're not doing this today.

To be clear, I think we should select the best guidance, and not treat Google or Roblox or anyone else as binding precedent...but I also feel compelled to mention this as an aside given the recent discussions about what it would take for Roblox to adopt AEPs (and in particular the fact that -- so far -- the divergence is minimal to nonexistent).

Just in that wasn't clear enough: I do not think Roblox's precedent should be a factor in this decision.

wora commented 3 months ago

Using item/items as generic field names for resources is a fine choice. Some Google AP actually used this naming pattern between 2009 and 2012.