Get linked objects

Given the ref of an object, returns a list of all objects which link to this object. Results are paged, so multiple requests may need to be made to retrieve the entire list.

ENDPOINT /api/v0-object/linked/[ref] (GET)

When generating URLs, [ref] is the ref of a store object.

Request

In addition to the ref of the store object, the URL may include some optional parameters.

attribute Restrict results to objects linked to this object in the given attribute, specified as the API code. For example, std:attribute:project.
qualifier When attribute is used, restrict further to objects linked with the given qualifier, for example dc:qualifier:alternative.
type Restrict to objects of a given type, for example, std:type:project
results Set results=refs to return results as their ref, or results=objects to return the full serialised object.
start The numeric index of the first result to return. Results are paged, so the API must be called repeatedly to fetch the entire list.

If results=objects is specified, the request must contain a sources parameter. This may be:

sources=NONE No additional sources, just the object information.
sources=ALL All available sources. It is not recommended you use this, except for manually exploring the API.
sources=s1,s2,... Specify the required sources as a comma separated list.

The request may include a transform parameter, which specifies a comma separated list of transforms to be applied to the object.

transform=restrict Apply Restrictions to the object before serialising it.

Response

This request can respond with following kinds, in addition to the generic kinds (see Introduction):

Kind Meaning
haplo:api-v0:object:store-query-results The request was successful and a list of linked objects has been returned
haplo:api-v0:object:sources-not-specified The sources parameter was not specified. Returns with HTTP status 400
haplo:api-v0:object:bad-query The object store query was invalid. Returns with HTTP status 400 and more information in the message

Along with the standard success and kind fields (see Introduction for explanation), the response contains a list of the linked objects.

If results=ref or no results parameter was specified, the refs property is an array of object references.

If results=objects was specified, the objects property is an array of objects in the standard JSON serialisation.

The results property contains the following nested properties:

  • count – the number of linked objects
  • start – the index of the first result in this page
  • end – the index of the result after the last result in this page
  • moretrue if there are more results to fetch.

If more is true, the request should be repeated with the start parameter set to the end property to fetch the next page of results.

Example

GET /api/v0-object/linked/83w92
{
  "success": true,
  "kind": "haplo:api-v0:object:store-query-results",
  "results": {
    "count": 4,
    "start": 0,
    "end": 4,
    "more": false
  },
  "refs": [
    "83w93",
    "81y84",
    "81y83",
    "81y82"
  ]
}