1. Description

These APIs provide direct Create, Read, Update, and Delete against data within an index.

Use the PUT and POST methods here with some caution.

Use of these APIs to load data into Globus Search for production workflows is discouraged. You should use the Ingest API for that purpose as it is more robust and provides higher throughput. However, the ability to push a single document can be useful without the full complexity of the Ingest API.

1.1. Access Controls on Entry & Subject Operations

Access to entry create, update and delete APIs may be restricted to certain users. The identity of the caller is determined based on the Bearer token provided to authenticate the API call.

1.2. Entry Operations

The Entry Operations APIs are used to retrieve and perform Create, Update and Delete operations directly on entries within an index. The various operations are carried out using the standard mapping to HTTP Methods: GET to retrieve and entry, DELETE to remove an entry, POST to create a new entry and PUT to update a pre-existing entry.

1.3. Subject Operations

The Subject Operations APIs are used to either query directly about a known Subject value, or to delete all data pertaining to a subject.

2. API Methods

2.1. Get Single Entry

URL

/v1/index/<index_id>/entry

Method

GET

Query Parameters

See the Query Parameters table below.

HTTP Headers

(optional) Authorization: Bearer <Globus Auth token> 1

Request Body

None

Response Body

A GMetaResult 2. The content array of the GMetaResult will always contain exactly one entry.

1 The token may have a urn:globus:scopes:search.api.globus.org scope and belong to a user with sufficient priveleges to view the Entry, or the Entry must be public

2 See the Query API documentation for the definition of GMetaResult

Table 1. Query Parameters
Parameter Name Description

subject

Required. 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

The entry_id of the entry to be operated upon. The value takes the same form as the id property of the GMetaEntry structure including being optional. When it is not present, it assumes the same default, "null" value, as a missing id property on a GMetaEntry.

2.1.1. 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'

2.2. Delete Single Entry

URL

/v1/index/<index_id>/entry

Method

DELETE

Query Parameters

Same as GET above

HTTP Headers

Authorization: Bearer <Globus Auth token> 1

Response Body

{ "removed": true }

1 The token must have the urn:globus:scopes:search.api.globus.org:all or urn:globus:scopes:search.api.globus.org:ingest scope, and must belong to a user with admin or write permissions against <index_id>

2.2.1. Examples

  • in the index 4de0e89e-a395-11e7-bc54-8c705ad34f60

  • with a subject of https://example.com/foo/bar

  • with a null entry_id

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

2.3. Create Single Entry

URL

/v1/index/<index_id>/entry

Method

POST

HTTP Headers

Authorization: Bearer <Globus Auth token> 1
Content-Type: application/json

Request Body

GMetaEntry 2

Response Body

{ "success": true }

1 The token must have the urn:globus:scopes:search.api.globus.org:all or urn:globus:scopes:search.api.globus.org:ingest scope, and must belong to a user with admin or write permissions against <index_id>

2 See the Ingest API documentation for the full definition of GMetaEntry

2.3.1. Examples

  • in the index 4de0e89e-a395-11e7-bc54-8c705ad34f60

  • with a subject of https://example.com/foo/bar

  • with a null entry_id

  • public visibility

curl -XPOST 'https://search.api.globus.org/v1/index/4de0e89e-a395-11e7-bc54-8c705ad34f60/entry' \
    --data '{
      "subject": "https://example.com/foo/bar",
      "visible_to": ["public"],
      "content": {
        "foo/bar": "some val"
      }
    }'
  • in the index 4de0e89e-a395-11e7-bc54-8c705ad34f60

  • with a subject of https://example.com

  • with an entry_id of foo/bar

  • public visibility

curl -XPOST 'https://search.api.globus.org/v1/index/4de0e89e-a395-11e7-bc54-8c705ad34f60/entry' \
    --data '{
      "subject": "https://example.com",
      "id": "foo/bar",
      "visible_to": ["public"],
      "content": {
        "foo/bar": "some val"
      }
    }'

2.4. Update Single Entry

URL

/v1/index/<index_id>/entry

Method

PUT

Query Parameters

Same as GET above

HTTP Headers

Authorization: Bearer <Globus Auth token> 1
Content-Type: application/json

Request Body

GMetaEntry

Response Body

{ "success": true }

1 The token must have the urn:globus:scopes:search.api.globus.org:all or urn:globus:scopes:search.api.globus.org:ingest scope, and must belong to a user with admin or write permissions against <index_id>

2.4.1. Examples

  • in the index 4de0e89e-a395-11e7-bc54-8c705ad34f60

  • with a subject of https://example.com/foo/bar

  • with a null entry_id

  • visible only to globus@globus.org (which has ID 46bd0f56-e24f-11e5-a510-131bef46955c)

curl -XPUT 'https://search.api.globus.org/v1/index/4de0e89e-a395-11e7-bc54-8c705ad34f60/entry' \
    --data '{
      "subject": "https://example.com/foo/bar",
      "visible_to": ["urn:globus:auth:identity:46bd0f56-e24f-11e5-a510-131bef46955c"],
      "content": {
        "foo/bar": "some new val"
      }
    }'

2.5. Get by Subject

URL

/v1/index/<index_id>/subject

Method

GET

Query Parameters

See the Query Parameters table below.

HTTP Headers

(optional) Authorization: Bearer <Globus Auth token> 1

Request Body

None

Response Body

GMetaResult

1 The token may have a urn:globus:scopes:search.api.globus.org scope and belong to a user with sufficient priveleges to view the Subject, or the Subject must contain public Entries

Table 2. Query Parameters
Parameter Name Description

subject

Required. The (url-encoded) subject to lookup

2.5.1. Examples

Fetch the data for subject http://example.com/abc from the index ccfa4ab6-7322-4982-9dd6-8ab1eb45f8eb

curl -XGET 'https://search.api.globus.org/v1/index/ccfa4ab6-7322-4982-9dd6-8ab1eb45f8eb/subject?subject=http%3A//example.com/abc'

2.6. Delete by Subject

URL

/v1/index/<index_id>/subject

Method

DELETE

Query Parameters

Same as GET above

HTTP Headers

Authorization: Bearer <Globus Auth token> 1

Request Body

None

Response Body

{ "removed": true }

1 The token must have the urn:globus:scopes:search.api.globus.org:all or urn:globus:scopes:search.api.globus.org:ingest scope, and must belong to a user with admin or write permissions against <index_id>

Note:

Deleting a subject deletes all entries in that subject, including those those which are not visible to the current user. Therefore, deleting all entries under a subject is not the same as deleting the subject itself.

2.7. DELETE by Query

Delete by query provides a powerful method for removing a large number of documents in a single operation.

But with great power comes great responsibility: delete by query should be used with extreme care as the operation cannot be "undone."

The operation removes an entire subject where there is a match on the query. That is, if even a single entry for a subject matches the query, then all entries, as well as the subject itself, will be removed from the index.

This is similar to the result of performing a query: the set of subjects deleted will exactly match the set of subjects returned by the query used for delete by query. Indeed, it is recommneded that a possible delete by query operation be first tested by executing the query. The query results, such as the total number of subjects returned, should be inspected and considered prior to executing the delete by query operation.

Note, however, that there is no guarantee that the subjects deleted using delete by query will exactly match the set of subjects returned by the query as the state of the index may continue to change between the operations.

Due to the broad capability of delete by query to change the state of the index, it can only be executed by a user with admin permissions on the index.

URL

/v1/index/<index_id>/delete_by_query

Method

POST

Query Parameters

None

HTTP Headers

Authorization: Bearer <Globus Auth token> 1

Request Body

GSearchRequest See note below.

Response Body

GDeleteByQueryResult, defined below

1 The token must have the urn:globus:scopes:search.api.globus.org:all or urn:globus:scopes:search.api.globus.org:ingest scope, and must belong to a user with admin or write permissions against <index_id>

Note:

Delete by query uses the same input structure as a normal query, GSearchRequest, but only makes use of the q, advanced_query, filters and query_template fields.

All other fields, including those related to pagination, do not change the full set of subjects which match a query, and are therefore ignored by the delete by query operation.

This allows the same GSearchRequest to be used with delete by query as may have been used for a testing or regular query request without need for alteration. The rule applies to delete-by-query requests which use query templates: the filtering/selection options of the template will be applied, but other properties of the template will be ignored.

Table 3. GDeleteByQueryResult
Field Name Type Description

num_subjects_deleted

Integer

The number of subjects removed as a result of a delete by query operation. May be 0 if the query did not match any subjects.

{
  "num_subjects_deleted": 100
}

© 2010- The University of Chicago Legal