Refactor generic /attributes router into attribute-specific routers

[alyssadai]

Given that our API is gradually expanding to accommodate requests for more specific metadata about specific attributes (e.g., versions of a specific pipeline), it makes sense to restructure the logic of existing /attributes routes to be more REST-compliant and intuitive for API consumers.

At the moment, we have two "top-level" subpaths in the /attributes router, which are:

• /attributes/{data_element_uri}/
• /attributes/{data_element_uri}/vocab

While the current level of abstraction makes it easy to accommodate new attributes in the graph, this structure is less intuitive in terms of what each endpoint returns, and gets tricky to expand in terms of the types of info returned. e.g., specific versions of the nb:Pipeline attribute:

• /attributes/{data_element_uri}/versions or even /attributes/nb:Pipeline/versions is not very elegant

Instead, it would be more helpful and maintainable to adopt a more conventional REST structure where top-level routers represent distinct entities (with potentially distinct operations and behaviours), and subpaths point to increasingly specific resources of those entities. This avoids path ambiguity for the end user cause by nesting everything under a single /attributes router, and makes the API more explicit and intuitive.

This can be seen in practice in the Stardog and GraphDB API docs.

Suggested path structure

• /attributes/ -> to return all Neurobagel attributes in the data model (i.e., keeping the current behaviour)
• and then one top-level router for each attribute we support introspection of (most likely, all the ones with controlled terms as objects):
  • /pipelines
  • /assessments
  • /diagnoses
  • /sex (?)
• per attribute router, there should be:
  • a root path / that returns available instances in the graph
  • a vocab path /vocab that returns the possible labels and term URLs from the corresponding vocab

NOTE The f-API would also need to be updated to reflect this change

[neurobagel-bot]

🚀 Issue was released in v0.4.0 🚀