[
https://issues.apache.org/jira/browse/USERGRID-791?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Brandon Shelley updated USERGRID-791:
-------------------------------------
Description:
Currently the verbiage of connections is exceptionally confusing. Out of the
docs, we support:
{code}
POST /users/[uuid]/likes/[uuid]
// No body?
// No target collection, just an orphaned uuid?
{code}
Which produces a structure like this:
{code}
/users/[uuid]:
{
"metadata": {
"connections": {
"likes": "/users/[uuid]/likes"
}
}
}
{code}
To which you can then call either:
{code}GET /users/[uuid]/likes{code}
OR!
{code}GET /users/[uuid]/connections/likes{code}
OR!!! (NOT IN THE DOCS?!)
{code}GET /users/[uuid]/connected/likes{code}
Then, confusingly, on the reverse, you can call:
{code}GET /pictures/[uuid]/connecting{code}
OR
{code}GET /pictures/[uuid]/connecting/likes{code}
Needless to say, this is exceptionally amgiuous and connect* is a mouthful.
*Proposal:*
In the POST request that creates the connection, rather than relying on URL
paths to confuse things, allow the user to define the parameters in the POST
body instead. Rough example:
_(Caveat: this may not architecturally work with the different "in" and "out"
verbs. That's ok, even with the "in" and "out" key objects under "connections",
it's still easier to understand than it is now)_
{code}
POST /[collection]/[uuid]/connect
// body:
{
"to": "/[collection]/uuid",
"in": "likedBy",
"out": "likes"
}
{code}
Then when retrieving:
{code}
GET /users/[uuid]
// Can we drop this from metadata, and instead include it in the top level?
{
"connections": {
"out": {
"likes": [ // should ALWAYS be an array
"/users/[uuid]",
"/pictures/[uuid]"
]
},
"in": {
"likedBy": [ // should ALWAYS be an array
"/users/[uuid]"
],
"dislikedBy": [
"/moderators/[uuid]"
]
}
}
}
{code}
Or, call it specifically:
{code}
GET /users/[uuid]/likes:
[ ... array of entities that [uuid] likes ... ]
{code}
{code}
GET /users/[uuid]/likedBy:
[ ... array of entities that like [uuid] ... ]
{code}
Or, call relationships:
{code}
GET /users/[uuid]/connections/in
[ ... array of entities that have inbound connections to [uuid] ... ]
{code}
{code}
GET /users/[uuid]/connections/out
[ ... array of entities that [uuid] has outbound connections to ... ]
{code}
{code}
GET /users/[uuid]/connections:
[ ... a mixed array of ALL entities connected to and from [uuid], ordered by
created date; 'type' would distinguish which collection each entity belongs to
... ]
{code}
*BONUS POINTS*
Connections are a pain in the ass because you ALWAYS need to make 2 API calls
in order to retrieve them. Let's add a paremeter to optionally resolve them
(yes, slow, that's OK - we can just add a disclaimer to docs). To make it
performant, we could include the cursor from the nested relationship array.
{code}
GET /users/[uuid]?resolveConnections=likes
(or!)
GET /users/[uuid]?resolveConnections=likes:uuid,name,firstName
{
"connections": {
"in": {
"likesCursor": "pagiationCursorGoesHere",
"likes": [ // should ALWAYS be an array
{
// an entity! But only this one is expanded
},
{
// an entity! But only this one is expanded
}
]
},
"out": {
"likedBy": [ // should ALWAYS be an array
"/users/[uuid]"
],
"dislikedBy": [
"/moderators/[uuid]"
]
}
}
}
{code}
was:
Currently the verbiage of connections is exceptionally confusing. Out of the
docs, we support:
{code}
POST /users/[uuid]/likes/[uuid]
// No body?
// No target collection, just an orphaned uuid?
{code}
Which produces a structure like this:
{code}
/users/[uuid]:
{
"metadata": {
"connections": {
"likes": "/users/[uuid]/likes"
}
}
}
{code}
To which you can then call either:
{code}GET /users/[uuid]/likes{code}
OR!
{code}GET /users/[uuid]/connections/likes{code}
OR!!! (NOT IN THE DOCS?!)
{code}GET /users/[uuid]/connected/likes{code}
Then, confusingly, on the reverse, you can call:
{code}GET /pictures/[uuid]/connecting{code}
OR
{code}GET /pictures/[uuid]/connecting/likes{code}
Needless to say, this is exceptionally amgiuous and connect* is a mouthful.
*Proposal:*
In the POST request that creates the connection, rather than relying on URL
paths to confuse things, allow the user to define the parameters in the POST
body instead. Rough example:
_(Caveat: this may not architecturally work with the different "in" and "out"
verbs. That's ok, even with the "in" and "out" key objects under "connections",
it's still easier to understand than it is now)_
{code}
POST /[collection]/[uuid]/connect
// body:
{
"to": "/[collection]/uuid",
"in": "likedBy",
"out": "likes"
}
{code}
Then when retrieving:
{code}
GET /users/[uuid]
// Can we drop this from metadata, and instead include it in the top level?
{
"connections": {
"out": {
"likes": [ // should ALWAYS be an array
"/users/[uuid]",
"/pictures/[uuid]"
]
},
"in": {
"likedBy": [ // should ALWAYS be an array
"/users/[uuid]"
],
"dislikedBy": [
"/moderators/[uuid]"
]
}
}
}
{code}
Or, call it specifically:
{code}
GET /users/[uuid]/likes:
[ ... array of entities that [uuid] likes ... ]
{code}
Or, call it specifically:
{code}
GET /users/[uuid]/likedBy:
[ ... array of entities that like [uuid] ... ]
{code}
Or, call relationships:
{code}
GET /users/[uuid]/connections/in
[ ... array of entities that have inbound connections to [uuid] ... ]
{code}
{code}
GET /users/[uuid]/connections/out
[ ... array of entities that [uuid] has outbound connections to ... ]
{code}
{code}
GET /users/[uuid]/connections:
[ ... a mixed array of ALL entities connected to and from [uuid], ordered by
created date; 'type' would distinguish which collection each entity belongs to
... ]
{code}
*BONUS POINTS*
Connections are a pain in the ass because you ALWAYS need to make 2 API calls
in order to retrieve them. Let's add a paremeter to optionally resolve them
(yes, slow, that's OK - we can just add a disclaimer to docs). To make it
performant, we could include the cursor from the nested relationship array.
{code}
GET /users/[uuid]?resolveConnections=likes
(or!)
GET /users/[uuid]?resolveConnections=likes:uuid,name,firstName
{
"connections": {
"in": {
"likesCursor": "pagiationCursorGoesHere",
"likes": [ // should ALWAYS be an array
{
// an entity! But only this one is expanded
},
{
// an entity! But only this one is expanded
}
]
},
"out": {
"likedBy": [ // should ALWAYS be an array
"/users/[uuid]"
],
"dislikedBy": [
"/moderators/[uuid]"
]
}
}
}
{code}
> Re-evaluation connections verbiage and either deprecate or offer alternative
> (alias) to old terminology
> -------------------------------------------------------------------------------------------------------
>
> Key: USERGRID-791
> URL: https://issues.apache.org/jira/browse/USERGRID-791
> Project: Usergrid
> Issue Type: Story
> Components: Stack
> Affects Versions: 2.0
> Reporter: Brandon Shelley
> Labels: features
>
> Currently the verbiage of connections is exceptionally confusing. Out of the
> docs, we support:
> {code}
> POST /users/[uuid]/likes/[uuid]
> // No body?
> // No target collection, just an orphaned uuid?
> {code}
> Which produces a structure like this:
> {code}
> /users/[uuid]:
> {
> "metadata": {
> "connections": {
> "likes": "/users/[uuid]/likes"
> }
> }
> }
> {code}
> To which you can then call either:
> {code}GET /users/[uuid]/likes{code}
> OR!
> {code}GET /users/[uuid]/connections/likes{code}
> OR!!! (NOT IN THE DOCS?!)
> {code}GET /users/[uuid]/connected/likes{code}
> Then, confusingly, on the reverse, you can call:
> {code}GET /pictures/[uuid]/connecting{code}
> OR
> {code}GET /pictures/[uuid]/connecting/likes{code}
> Needless to say, this is exceptionally amgiuous and connect* is a mouthful.
> *Proposal:*
> In the POST request that creates the connection, rather than relying on URL
> paths to confuse things, allow the user to define the parameters in the POST
> body instead. Rough example:
> _(Caveat: this may not architecturally work with the different "in" and "out"
> verbs. That's ok, even with the "in" and "out" key objects under
> "connections", it's still easier to understand than it is now)_
> {code}
> POST /[collection]/[uuid]/connect
> // body:
> {
> "to": "/[collection]/uuid",
> "in": "likedBy",
> "out": "likes"
> }
> {code}
> Then when retrieving:
> {code}
> GET /users/[uuid]
> // Can we drop this from metadata, and instead include it in the top level?
> {
> "connections": {
> "out": {
> "likes": [ // should ALWAYS be an array
> "/users/[uuid]",
> "/pictures/[uuid]"
> ]
> },
> "in": {
> "likedBy": [ // should ALWAYS be an array
> "/users/[uuid]"
> ],
> "dislikedBy": [
> "/moderators/[uuid]"
> ]
> }
> }
> }
> {code}
> Or, call it specifically:
> {code}
> GET /users/[uuid]/likes:
> [ ... array of entities that [uuid] likes ... ]
> {code}
> {code}
> GET /users/[uuid]/likedBy:
> [ ... array of entities that like [uuid] ... ]
> {code}
> Or, call relationships:
> {code}
> GET /users/[uuid]/connections/in
> [ ... array of entities that have inbound connections to [uuid] ... ]
> {code}
> {code}
> GET /users/[uuid]/connections/out
> [ ... array of entities that [uuid] has outbound connections to ... ]
> {code}
> {code}
> GET /users/[uuid]/connections:
> [ ... a mixed array of ALL entities connected to and from [uuid], ordered by
> created date; 'type' would distinguish which collection each entity belongs
> to ... ]
> {code}
> *BONUS POINTS*
> Connections are a pain in the ass because you ALWAYS need to make 2 API calls
> in order to retrieve them. Let's add a paremeter to optionally resolve them
> (yes, slow, that's OK - we can just add a disclaimer to docs). To make it
> performant, we could include the cursor from the nested relationship array.
> {code}
> GET /users/[uuid]?resolveConnections=likes
> (or!)
> GET /users/[uuid]?resolveConnections=likes:uuid,name,firstName
> {
> "connections": {
> "in": {
> "likesCursor": "pagiationCursorGoesHere",
> "likes": [ // should ALWAYS be an array
> {
> // an entity! But only this one is expanded
> },
> {
> // an entity! But only this one is expanded
> }
> ]
> },
> "out": {
> "likedBy": [ // should ALWAYS be an array
> "/users/[uuid]"
> ],
> "dislikedBy": [
> "/moderators/[uuid]"
> ]
> }
> }
> }
> {code}
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
