API for Relationships widget

[lustoykov]

See MusicConnectionMachine/RelationshipsG3#27

I don't have rights, so please add Assigness and Deadline: 02.04.2017

so yesterdey me, @martomi and @vviro had a meeting and here is what came out of the discussion

The basic idea is that we want to display in a somewhat-table view non-trivial relationships (almost like a surprise-fun-fact table - Mozart | Liked | Getting Drunk)

Entity | Relation | Entity

When a user on the IMSLP site and exploring our widget, one of the entities is always fixed (for instance Mozart).

Now we want to have a search bar, where user can type in. The search bar should be very smart and display autosuggestions in form of:

Relations Suggestions

• Entity1
• Entity2
  ...

Entities Suggestions

• Entity1
• Entity2
  ...

---

Whenever a user clicks one of the suggestions, we'd make an api call with Entity | Entity expecting relations as response or Entity | Relations expecting entities as response to display the table view Entity | Relation | Entity

Requirement: for the autosuggestions

• the API GET /autosuggest should accept:
  a single param query: { primaryEntity, searchInput, }

• the API should deliver:

{ 
   entitites: [ { title: '...', importance: '...', confidence: '...' }, { ... } ]
   relations: [ { title: '...', importance: '...', confidence: '...' }, { ... } ]
}

at least title is required, importance and confidence would be nice.

---

Requirement: for data display

• The API GET /relations should accept:
  a single param query: { primaryEntity: String, secondaryEntity: String, }

and return

{ 
   relations: [ { title: '...', importance: '...', confidence: '...' }, { ... } ]
}

• The API /entities should accept:
  a single param query: { primaryEntity: String, relation: String, }

and return

{ 
   entities: [ { title: '...', importance: '...', confidence: '...' }, { ... } ]
}

@martomi can you double check if the API as defined is OK? Please edit the post directly if I missed something.

@vviro also encourages us to talk to him more often.

[lustoykov]

@kordianbruck just for final confirmation - is elasticsearch / API in scope of the visualization group?
Because @Henni is asking good questions regarding design of the API? I had the impression they provide the API? Can we clarify this asap so we can collaborate more efficiently?

[lustoykov]

@Henni the query we're sending won't be an id, but a plain text from the search bar, I think subject_id might be misleading as name. Maybe subject and object is better?

Yes, so, if object couldn't be Getting Drunk, but only musicians, composers and pieces - that's OK. I only described ideal world, but you decide what to give as response (or what to save in the DB)

[kordianbruck]

@lustoykov we are not doing elastic at all. Instead you guys are going to utilize PostregreSQL Fulltext search capabilities by implementing the search api (which is then basically almost the same as the autocomplete endpoint)

[lustoykov]

OK then, so

• G3 / G4 provide database with entities / relation tables as described. G3 / G4 can you link your DB structure or describe it here?
• G5 implements the APIs and visualises the data as described

Is that the agreement?

[martomi]

Question regarding the GET /autosuggest endpoint:

Don't we need two parameters there? One is the primaryEntity and the other one the current input from the search field?

Also I think confidence and importance are not independent attributes in our context, one of them should be sufficient.

[lustoykov]

importance means how important the relation is (we want to display top 5 probably), confidence means how likely it is to be accurate? I agree on GET /autosuggest, edited my post.

[martomi]

Yes, I understand their meaning, but both of them are calculated from the number of occurrences of the said relations in the data we have. This makes them dependent on one another.

Unless we use another metric for the confidence such as tracking user feedback on said relations. In that case you might go with something simpler such as a field that contains an integer with the number of times the relation has been flagged by someone.

[Henni]

@lustoykov db schemata are currently discussed over here #28

[martomi]

@lustoykov GET /autosuggest would make more sense to deliver the following format in my opinion, but it's almost the same:

{ 
   entitites: {
        artists: [
            { id, name, artist_type, picture, dateOfBirth, placeOfBirth, dateOfDeath, nationality, tags, pseudonym, source_link }
            ...
        ],
        instruments: [
            {id, name }
            ...
        ],
        releases: [
            { id, title, format, date, country, label }
            ...
        ]
   }
   relations: [ 
         { title: '...', confidence: '...' }
          ... 
   ]
}

[lustoykov]

I don't mind, will adjust the frontend once the final API is there. Then the relations should be nested as well, because otherwise if I'd want to access the 3rd relation for instruments I'd need the count of artists.

[martomi]

@lustoykov What is the use case of that?

[lustoykov]

it is just more consistent design in my opinion, the split in entities and non-split in relations seems a bit arbitrary to me. anyways, I don't mind here much - whatever you prefer.

[martomi]

Entities have different types and underlying models hence the need for a split.

If you prefer a more consistent look, an alternative structure would be to drop entities altogether.

{ 
   artists: [
        { id, name, artist_type, picture, dateOfBirth, placeOfBirth, dateOfDeath, nationality, tags, pseudonym, source_link }
        ...
   ],
   instruments: [
        {id, name }
         ...
   ],
   releases: [
        { id, title, format, date, country, label }
         ...
    ]
   relations: [ 
         { title: '...', confidence: '...' }
          ... 
   ]
}

Those correspond to actual models in the backend.