Get Entry

Lookup a single Entry in a Search Index.

This returns a result document containing only the requested entry. You must have permissions to view the entry.

Method	GET
URL	/v1/index/<index_id>/entry
Authentication required?	Only for non-public entries
Required Roles	None
Response Body	A GMetaResult. The content array of the GMetaResult will always contain exactly one entry.

Authentication & Authorization

Tokens for this call must have one of these scopes.

urn:globus:scopes:search.api.globus.org:all
urn:globus:scopes:search.api.globus.org:search

You must have the owner or admin role to use bypass_visible_to

Parameters

Parameter Name	Required?	Description
subject	Yes	The subject containing the entry to be operated upon. The value takes the same form as the subject property of the GMetaEntry structure. The value should be url-encoded.
entry_id	No	The entry_id of the entry to be operated upon, if it is not `null`
result_format_version	No	One of {"2019-08-27", "2017-09-01"}. Defaults to 2019-08-27. When given as 2017-09-01, results will be returned in the legacy format.
bypass_visible_to	No	Defaults to False. Allowed for Index Admins only. When true, visible_to restrictions will be ignored for this lookup.

Examples

in the index 4de0e89e-a395-11e7-bc54-8c705ad34f60
with a subject of https://example.com/foo/bar
with a null entry_id

curl 'https://search.api.globus.org/v1/index/4de0e89e-a395-11e7-bc54-8c705ad34f60/entry?subject=https%3A%2F%2Fexample.com%2Ffoo%2Fbar'

in the index 4de0e89e-a395-11e7-bc54-8c705ad34f60
a subject of https://example.com
with an entry_id of foo/bar

curl 'https://search.api.globus.org/v1/index/4de0e89e-a395-11e7-bc54-8c705ad34f60/entry?subject=https%3A%2F%2Fexample.com&entry_id=foo%2Fbar'

Response Schemas

GMetaResult

These are components in a search result.

A GMetaResult is a structure similar to a GMetaEntry from the Ingest API, with the following significant differences:

visibility information is not exposed; i.e. visible_to is not included
metadata for any subject may be an aggregate of multiple documents with different visibility rules or sources. Thus, the result is always returned as an array in which each element represents data provided by a different source or with different visibility

GMetaResult version 2019-08-27

Field Name Type Description

subject

String

the resource described by this metadata, often a URI

entries

Array

An array of objects containing the data pertaining to the subject.

Each object has the fields content, entry_id, and matched_principal_sets. The content is an object with the entry data which was sent to Search, and the entry_id is its ID. If there are any assigned principal_sets for the entry which match the current caller, they will be returned as an array of strings in matched_principal_sets.

{
  "entries": [
    {
      "content": {
        "alpha": {
          "beta": "gamma"
        }
      },
      "matched_principal_sets": [],
      "entry_id": null
    },
    {
      "content": {
        "alpha": {
          "beta": "delta"
        }
      },
      "matched_principal_sets": [],
      "entry_id": "with_delta"
    }
  ],
  "subject": "http://example.com"
}

GMetaResult version 2017-09-01 (legacy format)

Field Name	Type	Description
subject	String	the resource described by this metadata, often a URI
content	Array	an array of objects containing the metadata pertaining to the subject
entry_ids	Array	an array of Entry IDs matching the content such that the entry ID at index i has content found in content[i]. See note below

Note

entry_ids and content are kept separate to maintain backwards compatibility. They can easily be unified with a zip operation in many programming languages.

{
  "entries": [
    {
      "content": {
        "alpha": {
          "beta": "gamma"
        }
      },
      "matched_principal_sets": [],
      "entry_id": null
    }
  ],
  "subject": "http://example.com"
}

Note how, in the example below, the new format makes it easier to associate entry_id values with content blobs. Additionally, this new format is more extensible — if new fields are needed in the new format, they can be added as siblings of the content and entry_id fields.

New Format (2019-08-27) Old Format (2017-09-01)

Table 1. Format Comparison
New Format (2019-08-27)	Old Format (2017-09-01)
`{ "entries": [ { "content": { "alpha": { "beta": "gamma" } }, "matched_principal_sets": [], "entry_id": null }, { "content": { "alpha": { "beta": "delta" } }, "matched_principal_sets": [], "entry_id": "with_delta" } ], "subject": "http://example.com" }`	`{ "content": [ { "alpha": { "beta": "gamma" } }, { "alpha": { "beta": "delta" } } ], "entry_ids": [ null, "with_delta" ], "subject": "http://example.com" }`
each entry is a complete, standalone subdocument	entry_ids needs to be zipped with content to make sense of the structure

{
  "entries": [
    {
      "content": {
        "alpha": {
          "beta": "gamma"
        }
      },
      "matched_principal_sets": [],
      "entry_id": null
    },
    {
      "content": {
        "alpha": {
          "beta": "delta"
        }
      },
      "matched_principal_sets": [],
      "entry_id": "with_delta"
    }
  ],
  "subject": "http://example.com"
}

{
  "content": [
    {
      "alpha": {
        "beta": "gamma"
      }
    },
    {
      "alpha": {
        "beta": "delta"
      }
    }
  ],
  "entry_ids": [
    null,
    "with_delta"
  ],
  "subject": "http://example.com"
}

each entry is a complete, standalone subdocument

entry_ids needs to be zipped with content to make sense of the structure