New API endpoint: GET /api/v1/concepts

kriskelly commented 9 years ago

GET /api/v1/concepts

Optional query parameters:

level: 0, 1, 2 We need to talk more about this before implementing anything, see comments below parent: uid of the parent (e.g. the 'Quill Grammar' parent concept)

Proposed structure for the JSON response:

[
  {
    name: "It's",
    display_name: "It's (Contractions)",
    uid: "abcde12345",
    level: 0,
    parent: "defghi567689"
  }
]

wlaurance commented 9 years ago

Do we want to add parent and children where parent: String(uid) and children: [String(uid)...]?

kriskelly commented 9 years ago

@wlaurance Depends, is that useful for the Quill Grammar form? If not, we could leave it until there's a solid use case.

wlaurance commented 9 years ago

For now, we using the 3 drop down boxes to build the chain of level 2,1,0 concepts. Since the data set is small, we can get away with 3 or less HTTP requests or less.

Proposal 1

To fill the concept_level_2 box GET /api/v1/concepts?level=2

To fill the concept_level_1 box GET /api/v1/concepts?level=1

To fill the concept_level_0 box GET /api/v1/concepts?level=0

In this proposal, the concept object will need to include a parent id and children id list.

Proposal 2

To fill the concept_level_2 box GET /api/v1/concepts?level=2

To fill the concept_level_1 box GET /api/v1/concepts?level=1&parent=concept_level_2_id

To fill the concept_level_0 box GET /api/v1/concepts?level=0&parent=concept_level_1_id

In this proposal, the concept object won't need to include the parent id and children id list because the LMS replaces the functionality.

Proposal 3

GET /api/v1/concepts and concept objects have parent id and children list. Then the client manually builds the drop downs.

wlaurance commented 9 years ago

Going forward, we have accepted a modified proposal 3,

With GET /api/v1/concepts, with a concept structure described in the first comment https://github.com/empirical-org/Empirical-Core/issues/818#issue-99067642

kriskelly commented 9 years ago

@wlaurance @marcellosachs We discussed this briefly today, but there are a few options for indicating the depth of a node within the tree.

The first is to return a calculated level value like we talked about before, meaning level=0 refers to the leaf nodes of the tree. The major down side to this is because the way tree traversal works, you start from the root nodes (aka the top of the tree) and traverse toward the leaves. Meaning you would typically start at a depth of 0 or 1 and increase at each level. The upshot is that the depth of the tree (3 levels) would have to be hard coded in the LMS in order for this to work.
The 2nd option is to flip the level values so that 0 refers to the root nodes, and 2 refers to the leaf nodes. This would involve another set of assumptions at the Quill Grammar level about what level refers to what set of nodes in the tree. If the LMS was extended in the future so that all the current root nodes have a "Quill Grammar" node as a parent, this would bump the levels all off by 1 and necessitate changes to Quill Grammar. I think this parameter ought to be called something like depth to better convey info about where it lives in the tree. This is the one I vote for, btw.
The 3rd option is to store the level info as another column in the table. That way you could have whatever values you want in the level field and it wouldn't have to change if the tree structure changes. I think this is an anti-pattern if the level value is supposed to reflect the concept's placement within the tree.

Thoughts?

kriskelly commented 9 years ago

Side note to the last note: I'm also pretty tired and it might be that there's an easy way to traverse the tree in reverse, in which case ignore my last comment.

marcellosachs commented 9 years ago

@wlaurance @kriskelly I'm a bit confused as to what the resolution was on this. Are level, and parent_uid still optional params? Will 'level' be indicated in the individual records returned? (im confused as to what mix of proposal 3 and #818 (comment) we are going with)

marcellosachs commented 9 years ago

re a conversation with @wlaurance on slack :

request (for now) will have no optional params. Simply GET '/api/v1/concepts'

response will be an array of concepts, where each concept includes the indication of its parent_uid and children_uids, as well as its level.

empirical-org / Empirical-Core

New API endpoint: GET /api/v1/concepts #818