Description

The Entry Direct API is 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.

Get Single Entry

URL

/v1/index/<index_name>/entry

Method

GET

Query Parameters

See the Query Parameters table below.

HTTP Headers

(optional) Authorization: Bearer <Globus Auth token with scope urn:globus:scopes:search.api.globus.org:all> if requesting access to an entry protected with a visible_to list.

Request Body

None

Response Body

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

Error Responses

HTTP Code 404: The specified index_name, subject or entry_id does not exist or the user is not authorized to view this entry.

The body will contain a GError document

Table 1. Query Parameters
Parameter Name Required? Description

subject

True

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

False

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.

cURL Example 1

Looking up the entry

  • 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'

cURL Example 2

Looking up the entry

  • 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'

Delete Single Entry

URL

/v1/index/<index_name>/entry

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 404: The specified index_name, subject or entry_id does not exist or the user is not authorized to view this entry.

HTTP Code 403: Forbidden if the identity with the bearer token is not permitted to use this API.

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

The body will contain a GError document

cURL Example 1

Deleting the entry

  • 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'

Create Single Entry

URL

/v1/index/<index_name>/entry

Method

POST

HTTP Headers

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

Content-Type: must be "application/json"

Request Body

GMetaEntry

Response Body

{ "success": true }

Error Responses

HTTP Code 404: The specified index_name does not exist

HTTP Code 400: If the provided GMetaEntry is incomplete or invalid.

HTTP Code 403: Forbidden if the identity with the bearer token is not permitted to use this API.

HTTP Code 409: An entry with the same subject and entry_id already exists associated with the primary identity of the user requesting the operation OR if the index is Locked for writing.

The body will contain a GError document

cURL Example 1

Creating the entry

  • 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"
      }
    }'

cURL Example 2

Creating the entry

  • 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"
      }
    }'

Update Single Entry

URL

/v1/index/<index_name>/entry

Method

PUT

Query Parameters

Same as GET above

HTTP Headers

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

Content-Type: must be "application/json"

Request Body

GMetaEntry

Response Body

{ "success": true }

Error Responses

HTTP Code 404: The specified index_name, subject or entry_id does not exist or the user is not authorized to view this entry.

HTTP Code 400: If the provided GMetaEntry is incomplete or invalid.

HTTP Code 403: Forbidden if the identity with the bearer token is not permitted to use this API.

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

The body will contain a GError document

cURL Example 1

Updating the entry

  • 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"
      }
    }'
Note:

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.


© 2010- The University of Chicago Legal