Faceted paper browsing for observatories

Backend implementation for orkg-frontend!1175 (merged)

Observatory Filters

Observatory Filter

{
  "id": "R1234",
  "observatory_id": "00000000-0000-0000-0000-000000000000",
  "label": "Some label",
  "created_at": "2022-01-01T00:00:00.000000+00:00",
  "created_by": "00000000-0000-0000-0000-000000000000",
  "path": ["reports", "P60013"],
  "range": "Pattern",
  "exact": true,
  "featured": false
}

GET /api/observatories/{observatoryId}/filters

• Lists all observatory filters for the specified observatory (paged).
• Status codes
  • 200 OK

GET /api/observatories/{observatoryId}/filters/{filterId}

• Retrieves an observatory filter.
• Status codes
  • 200 OK
  • 404 NOT FOUND

POST /api/observatories/{observatoryId}/filters

• Creates a new filter for the specified observatory.

• Requirements

  • The user needs to be logged in
  • The user needs to be a curator or a member of the observatory

• Status codes

  • 201 CREATED
  • 400 BAD REQUEST
  • 404 NOT FOUND
• Request object

  {
    "label": "Some label",
    "path": ["reports", "P60013"],
    "range": "Pattern",
    "exact": true,
    "featured": false
  }

PATCH /api/observatories/{observatoryId}/filters/{filterId}

• Updates the specified filter.

• Requirements

  • The user needs to be logged in
  • The user needs to be a curator or a member of the observatory

• Status codes

  • 204 NO CONTENT
  • 404 NOT FOUND
• Request object (all fields are optional)

  {
    "label": "Some label",
    "path": ["P105059", "P60013"],
    "range": "Pattern",
    "exact": true,
    "featured": false
  }

DELETE /api/observatories/{observatoryId}/filters/{filterId}

• Deletes the specified observatory filter.
• Requirements
  • The user needs to be logged in
  • The user needs to be a curator or a member of the observatory
• Status codes
  • 204 NO CONTENT
  • 404 NOT FOUND

Resource Endpoints

GET /api/resources/?q={searchString}&baseClass={baseClass}

• Lists all resources whose label fuzzy matches searchString and are an instance of baseClass (paged).
• Status codes
  • 200 OK

Note: It might make sense (or not) to integrate this into the /api/resources endpoint. However, this would massively decrease the performance of the /api/resources endpoint, whenever the baseClass parameter is used. This technically also accesses data outside of the resource respository, as the class hierarchy information is not part of it, and the in-memory implementation would have a hard time of accessing that information.

Observatory Endpoints

Filter Config

A filter config is a url-encoded json-list of search filters. Each search filter is of the following structure:

{
  "path": ["P105059", "P60013"],
  "range": "Pattern",
  "values": [
    {
      "op": "EQ",
      "value": "some value"
    }
  ],
  "exact": false
}

Field	Description
path	Describes the path from the contribution node of a paper to the node that should be matched, where every entry stands for the predicate id of a statement. For exmaple the path provided in the example above matches node n in the following graph: (:Paper)-[P31]->(:Contribution)-[P105059]->(:Thing)-[P60013]->(n:Thing)
range	The class id that represents the range of the value that should be matched. Subclasses will also be considered when matching.
values	A list that contains the actual values that should be matched. Each value consists of an op field, which describes the logical matching operation, and a value field, which is the value that needs to match. Multiple value entries are logically combined with an OR operation.
exact	Whether to exactly match the given path. If true, the given path needs to exactly match, starting from the contribution resource. If false, the given path needs to exactly match, starting at any node in the subgraph of the contribution or the contribution node itself. The total path length is then limited to 10, including the length of the specified path, starting from the contribution node.

Op	Operation
EQ	Equals
NE	Not equals
LT	Less than
LE	Less or equal than
GE	Greater than
GT	Greater or equal than

Multiple filters in the filter config are logically combined with an AND operation.

GET /api/observatories/{observatoryId}/papers?filterConfig={filterConfig}&visibility={visibility}

• Lists all papers of the specified observatory, whose contributions match the given filterConfig and visibility (paged). Both parameters are optional.
• Sorting
  • Sorting is supported for the following fields: id, created_by, created_at. It is also possible to sort by the matched value of each search filter. To sort by the first search filter, the parameter value0 can be used. If a second search filter is defined, the parameter value1 can be used. By default, elements are sorted by created_at DESC.
• Status codes
  • 200 OK
  • 400 BAD REQUEST (when filter config is invalid)

Note: This endpoint should be merged with the paper content-type endpoint. But for now, we decided against it, as the adoption of the new paper endpoint is not quite there yet, and it is simpler to merge the endpoint as-is and update it later.