Graph adjacency API

[pudo]

At the moment, the only way of retrieving the graph context (adjacencies) of an entity via the API is to call /entities/<xxx>?nested=true. This will return the entity and all linked entities (see https://www.opensanctions.org/faq/26/nested/ for details).

Problem / requirements

While this works well for entities with a small adjacency set (e.g. a Person with two Family links and two Sanctions), it becomes problematic for super nodes (with many links), in particular Position entities which have hundreds or even thousands of holders. In those cases, the API response will easily reach megabytes in size, and take a long time to compute.

As a solution for this issue occurring on our website, we'd like to be able to paginate the relationship tables shown (e.g. show only the 50 most recent position holders by default). To provide this function, we need an API endpoint that allows:

a. Getting the list of adjacent entities linked to a root entity X with ?limit= and ?offset= support for pagination.
b. Filtering the adjacency list on the (stub) property name of the field in which the adjacencies are allowed to occur (e.g. "For this Person entity, show me the adjacent sanctions 51 thru 100"). This should be identified by outbound property name and not the schema of the adjacent entity, because entities could be connected in several ways.
c. Nest a second level of adjacent entities into the paginated responses. For example, if I am looking at a Person and fetch the ownershipOwner property, the resulting Ownership entities will effectively be link entities (schema.edge = true), and we should return the relevant asset (the thing being owned) alongside the main response.

Design

API endpoint:

Design 1

If we put this endpoint:

GET /entities/<xxx>/adjacent/<prop>

{
   "results": {....}
   "limit": 50,
   "offset": 0,
   "total": 23
}

How does the client know which props to ask for? A given schema may have dozens of possible link props, so it would be great if the client already had some form of aggregated adjacency overview (e.g. as part of the /entities/<xxx> response, or from /entities/<xxxx>/adjacent? Otherwise we'd send out 60 requests to get a response on 1 or 2.

Design 2

We can also group it:

GET /entities/<xxx>/adjacent?prop=*

{
  "ownershipOwner": {
     "results": {....}
     "limit": 50,
     "offset": 0,
     "total": 23
  }
}

This could return the first N (limit) of each prop by default, filling the screen for 90% of all users. If a new page is chosen, a request a la prop=ownershipOwner&offset=50 would be sent to fill up the second page?