Description

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

GET by Subject

URL

/v1/index/<index_name>/subject

Method

GET

Query Parameters

See the Query Parameters table below.

HTTP Headers

Authorization: Bearer <Globus Auth token with scope urn:globus:scopes:search.api.globus.org:all>

Request Body

None

Response Body

GMetaResult

Error Responses

HTTP Code 401: No Bearer token was provided, or one was provided with incorrect authorization.

HTTP Code 403: Forbidden if the identity associated with the bearer token is not permitted to access this index.

HTTP Code 404: Either the requested document does not exist, or it does exist, but is not visible to the caller.

The body will contain a GError document

Table 1. Query Parameters
Parameter Name Required? Description

subject

True

The (url-encoded) subject to lookup

Example

The following example fetches the data for subject http://example.com/abc from the index exampleindex

GET
https://search.api.globus.org/v1/index/exampleindex/subject?subject=http%3A//example.com/abc

DELETE by Subject

URL

/v1/index/<index_name>/subject

Method

DELETE

Query Parameters

Same as GET above

HTTP Headers

Authorization: Bearer <Globus Auth token with scope urn:globus:scopes:search.api.globus.org:all>

Request Body

None

Response Body

{ "removed": true }

Error Responses

HTTP Code 401: No Bearer token was provided, or one was provided with incorrect authorization.

HTTP Code 403: Forbidden if the identity associated with the bearer token is not permitted to access this index.

HTTP Code 404: Either the requested document does not exist, or it does exist, but is not visible to the caller.

HTTP Code 409: Conflict if the index is Locked for writing.

The body will contain a GError document

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.

DELETE by Query

Delete by query provides a powerful method for removing a large number of documents in a single operation. Note that 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. Stated again, use delete by query with extreme caution.

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

URL

/v1/index/<index_name>/delete_by_query

Method

POST

Query Parameters

None

HTTP Headers

Authorization: Bearer <Globus Auth token with scope urn:globus:scopes:search.api.globus.org:all>

Request Body

GSearchRequest See note below.

Response Body

GDeleteByQueryResult

Error Responses

HTTP Code 401: No Bearer token was provided, or one was provided with incorrect authorization.

HTTP Code 403: Forbidden if the identity associated with the bearer token is not associated with an admin role on the named index.

HTTP Code 404: The specified index does not exist.

HTTP Code 409: Conflict if the index is Locked for writing.

The body will contain a GError document

Note:

Delete by query uses the same input structure as a normal query, GSearchRequest, however it 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 same rule applies to query templates: the filtering/selection options of the template will be applied, but other properties of the template will be ignored.


© 2010- The University of Chicago Legal