[jira] [Created] (USERGRID-791) Re-evaluation connections verbiage and either deprecate or offer alternative (alias) to old terminology

["Brandon Shelley (JIRA)" <ji...@apache.org>]

Brandon Shelley created USERGRID-791:
----------------------------------------

             Summary: 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


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: 

{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}



--
This message was sent by Atlassian JIRA
(v6.3.4#6332)