Nothing Special   »   [go: up one dir, main page]

Skip to content

Requests

Requests

Used for interacting with requests.

Get a request

GET /api/requests/{request_id}

Parameters

Name Type Location Description
request_id string path The request's public identifier.
accept string header - application/json (default)
- application/vnd.inveniordm.v1+json (not yet)

Request

GET /api/requests/{request_id} HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "created": "2020-11-27 10:52:23.945755",
  "created_by": {"user": "1"},
  "expires_at": null,
  "id": "{request_id}",
  "is_closed": False,
  "is_expired": False,
  "is_open": False,
  "links": {
    "self": "{scheme+hostname}/api/requests/{request_id}",
    "actions": {
      "accept": "{scheme+hostname}/api/requests/{request_id}/actions/accept",
      "cancel": "{scheme+hostname}/api/requests/{request_id}/actions/cancel",
      "decline": "{scheme+hostname}/api/requests/{request_id}/actions/decline",
      "submit": "{scheme+hostname}/api/requests/{request_id}/actions/submit"
    },
  },
  "number": "1",
  "receiver": {"user": "2"},
  "revision_id": 1,
  "status": "draft",
  "title": "Foo bar",
  "topic": {"record": {record_id}},
  "type": "default-request",
  "updated": "2020-11-27 10:52:23.969244",
}

Update a request

Updating a request is not supported yet.

Because only some properties of a request can be updated manually, updating a request is disabled until it can be handled properly.

PUT /api/requests/{request_id}

Parameters

Name Type Location Description
request_id string path The request's public identifier.
accept string header - application/json (default)
- application/vnd.inveniordm.v1+json (not yet)

Request

PUT /api/requests/{request_id} HTTP/1.1
Content-Type: application/json

{
  "expires_at": null,
  "id": "{request_id}",
  "number": "{request_number}",
  "revision_id": 1,
  "status": "draft",
  "title": "A new title",
  "type": "default-request"
}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "created": "2020-11-27 10:52:23.945755",
  "created_by": {"user": "1"},
  "expires_at": null,
  "id": "{request_id}",
  "is_closed": False,
  "is_expired": False,
  "is_open": False,
  "links": {
    "self": "{scheme+hostname}/api/requests/{request_id}",
    "actions": {
      "accept": "{scheme+hostname}/api/requests/{request_id}/actions/accept",
      "cancel": "{scheme+hostname}/api/requests/{request_id}/actions/cancel",
      "decline": "{scheme+hostname}/api/requests/{request_id}/actions/decline",
      "submit": "{scheme+hostname}/api/requests/{request_id}/actions/submit"
    }
  },
  "number": "{request_number}",
  "receiver": {"user": "2"},
  "revision_id": 2,
  "status": "draft",
  "title": "A new title",
  "topic": {"record": "abcd-1234"},
  "type": "default-request",
  "updated": "2020-11-28 10:52:23.969244",
}

Search requests

Used for listing all requests you can interact with.

GET /api/requests

Parameters

Name Type Location Description
q string query Search query used to filter results based on ElasticSearch's query string syntax.
sort string query Sort search results. Built-in options are "bestmatch", "name", "newest", "oldest" (default: "bestmatch" or "newest").
size integer query Specify number of items in the results page (default: 10).
page integer query Specify the page of results.
accept string header - application/json (default)
- application/vnd.inveniordm.v1+json

Note that "bestmatch" is only available as a sort option on requests that provide a query string as a q parameter, in which case it is the default sort type. If no query string is provided in the request, the default sort type is "newest". In this case a "bestmatch" value is ignored and the default "newest" sort is used.

Request

GET /api/requests HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "hits": {
    "hits": [
      {
        "created": "2020-11-27 10:52:23.945755",
        "created_by": {"user": "1"},
        "expires_at": null,
        "id": "{request_id}",
        "is_closed": False,
        "is_expired": False,
        "is_open": False,
        "links": {
          "self": "{scheme+hostname}/api/requests/{request_id}",
          "actions": {
            "accept": "{scheme+hostname}/api/requests/{request_id}/actions/accept",
            "cancel": "{scheme+hostname}/api/requests/{request_id}/actions/cancel",
            "decline": "{scheme+hostname}/api/requests/{request_id}/actions/decline",
            "submit": "{scheme+hostname}/api/requests/{request_id}/actions/submit"
          }
        },
        "number": "{request_number}",
        "receiver": {"user": "2"},
        "revision_id": 2,
        "status": "draft",
        "title": "A new title",
        "topic": {"record": "abcd-1234"},
        "type": "default-request",
        "updated": "2020-11-28 10:52:23.969244",
      }
      ...
    ],
    "total": 2
  },
  "sortBy": "newest",
  "links": {
    "self": "{scheme+hostname}/api/requests?page=1&size=25&sort=newest"
  }
}

Request Actions

Used for interacting with a request's lifecyle.

Request submission

A request is submitted via the draft and record APIs.

Accept a request

Reviewer-only

Only a request's reviewer can accept it.

POST /api/requests/{request_id}/actions/accept

Parameters

Name Type Location Description
request_id   string path The request's public identifier.
payload object body The data associated with the comment. See Comment Payload.
accept string header - application/json (default)
- application/vnd.inveniordm.v1+json (not yet)

Request

POST /api/requests/{request_id}/actions/accept HTTP/1.1
{
  "payload": {"content": "You are in!", "format": "html"}
}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "created": "2020-11-27 10:52:23.945755",
  "created_by": {"user": "1"},
  "expires_at": null,
  "id": "{request_id}",
  "is_closed": True,
  "is_expired": False,
  "is_open": False,
  "links": {
    "self": "{scheme+hostname}/api/requests/{request_id}",
    "actions": {
      "accept": "{scheme+hostname}/api/requests/{request_id}/actions/accept",
      "cancel": "{scheme+hostname}/api/requests/{request_id}/actions/cancel",
      "decline": "{scheme+hostname}/api/requests/{request_id}/actions/decline",
      "submit": "{scheme+hostname}/api/requests/{request_id}/actions/submit"
    }
  },
  "number": "{request_number}",
  "receiver": {"user": "2"},
  "revision_id": 2,
  "status": "accepted",
  "title": "A new title",
  "topic": {"record": "abcd-1234"},
  "type": "default-request",
  "updated": "2020-11-28 10:52:23.969244",
}

Cancel a request

Creator-only

Only a request's creator can cancel it. A request's reviewer can decline though.

POST /api/requests/{request_id}/actions/cancel

Parameters

Name Type Location Description
request_id string path The request's public identifier.
payload object body The data associated with the comment. See Comment Payload.
accept string header - application/json (default)
- application/vnd.inveniordm.v1+json (not yet)

Request

POST /api/requests/{request_id}/actions/cancel HTTP/1.1
{
  "payload": {"content": "Didn't mean to do that!", "format": "html"}
}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "created": "2020-11-27 10:52:23.945755",
  "created_by": {"user": "1"},
  "expires_at": null,
  "id": "{request_id}",
  "is_closed": True,
  "is_expired": False,
  "is_open": False,
  "links": {
    "self": "{scheme+hostname}/api/requests/{request_id}",
    "actions": {
      "accept": "{scheme+hostname}/api/requests/{request_id}/actions/accept",
      "cancel": "{scheme+hostname}/api/requests/{request_id}/actions/cancel",
      "decline": "{scheme+hostname}/api/requests/{request_id}/actions/decline",
      "submit": "{scheme+hostname}/api/requests/{request_id}/actions/submit"
    }
  },
  "number": "{request_number}",
  "receiver": {"user": "2"},
  "revision_id": 2,
  "status": "cancelled",
  "title": "A new title",
  "topic": {"record": "abcd-1234"},
  "type": "default-request",
  "updated": "2020-11-28 10:52:23.969244",
}

Decline a request

Reviewer-only

Only a request's reviewer can decline it. A request's creator can cancel it though.

POST /api/requests/{request_id}/actions/decline

Parameters

Name Type Location Description
request_id string path The request's public identifier.
payload object body The data associated with the comment. See Comment Payload.
accept string header - application/json (default)
- application/vnd.inveniordm.v1+json (not yet)

Request

POST /api/requests/{request_id}/actions/decline HTTP/1.1
{
  "payload": {"content": "You are not in!", "format": "html"}
}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "created": "2020-11-27 10:52:23.945755",
  "created_by": {"user": "1"},
  "expires_at": null,
  "id": "{request_id}",
  "is_closed": True,
  "is_expired": False,
  "is_open": False,
  "links": {
    "self": "{scheme+hostname}/api/requests/{request_id}",
    "actions": {
      "accept": "{scheme+hostname}/api/requests/{request_id}/actions/accept",
      "cancel": "{scheme+hostname}/api/requests/{request_id}/actions/cancel",
      "decline": "{scheme+hostname}/api/requests/{request_id}/actions/decline",
      "submit": "{scheme+hostname}/api/requests/{request_id}/actions/submit"
    }
  },
  "number": "{request_number}",
  "receiver": {"user": "2"},
  "revision_id": 2,
  "status": "declined",
  "title": "A new title",
  "topic": {"record": "abcd-1234"},
  "type": "default-request",
  "updated": "2020-11-28 10:52:23.969244",
}

Request Events

Used for interacting with request events.

Submit a comment on a request

POST /api/requests/{request_id}/comments

Parameters

Name Type Location Description
request_id string path The request's public identifier.
payload object body The data associated with the comment. See Comment Payload.
accept string header - application/json (default)
- application/vnd.inveniordm.v1+json (not yet)

Comment Payload

Name Type Location Description
content string body The comment's textual content.
format string body The format of the textual content. Only "html" accepted for now.

Request

POST /api/requests/{request_id}/comments HTTP/1.1
Content-Type: application/json

{
  "payload": {
    "content": "I would use these subject terms to align the record with others in the community.",
    "format": "html"
  }
}

Response

HTTP/1.1 201 CREATED
Content-Type: application/json

{
  "created_by": {"user": "1"},
  "created": "2020-11-27 10:52:23.945755",
  "id": "{comment_id}",
  "links": {
    "self": "{scheme+hostname}/api/requests/{rquest_id}/comments/{comment_id}"
  },
  "payload": {
    "content": "I would use these subject terms to align the record with others in the community.",
    "format": "html"
  },
  "revision_id": 1,
  "type": "C",
  "updated": "2020-11-27 10:52:23.969244",
}

The event type

Comments are a kind of event related to a request. All events follow the same pattern: they have a type field identifying their type and a payload field with their specific data.

Get a comment

GET /api/requests/{request_id}/comments/{comment_id}

Parameters

Name Type Location Description
request_id string path The request's public identifier.
comment_id string path The comment's public identifier
accept string header - application/json (default)
- application/vnd.inveniordm.v1+json (not yet)

Request

GET /api/requests/{request_id}/comments/{comment_id} HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "created": "2020-11-27 10:52:23.945755",
  "created_by": {"user": "1"},
  "id": "{comment_id}",
  "links": {
    "self": "{scheme+hostname}/api/requests/{rquest_id}/comments/{comment_id}"
  },
  "payload": {
    "content": "I would use these subject terms to align the record with others in the community.",
    "format": "html"
  },
  "revision_id": 1,
  "type": "C",
  "updated": "2020-11-27 10:52:23.969244",
}

Update a comment

PUT /api/requests/{request_id}/comments/{comment_id}

Parameters

Name Type Location Description
request_id string path The request's public identifier.
comment_id string path The comment's public identifier
payload object body The data associated with the comment. See above.
accept string header - application/json (default)
- application/vnd.inveniordm.v1+json (not yet)

Request

PUT /api/requests/{request_id}/comments/{comment_id} HTTP/1.1
Content-Type: application/json

{
  "payload": {
    "content": "I would use these subject terms to align this record and the other one with others in the community.",
    "format": "html"
  }
}

Response

HTTP/1.1 200 OK
Content-Type: application/json


{
  "created": "2020-11-27 10:52:23.945755",
  "created_by": {"user": "1"},
  "id": "{comment_id}",
  "links": {
    "self": "{scheme+hostname}/api/requests/{rquest_id}/comments/{comment_id}"
  },
  "payload": {
    "content": "I would use these subject terms to align this record and the other one with others in the community.",
    "format": "html"
  },
  "revision_id": 2,
  "type": "C",
  "updated": "2020-11-27 10:55:23.969244",
}

Delete a comment

DELETE /api/requests/{request_id}/comments/{comment_id}

Deleting a comment will clear its content and mark it as a "deleted comment event". You can only delete your own comments unless you are a request's reviewer or admin.

Parameters

Name Type Location Description
request_id string path The request's public identifier.
comment_id string path The comment's public identifier
accept string header - application/json (default)
- application/vnd.inveniordm.v1+json (not yet)

Request

DELETE /api/requests/{request_id}/comments/{comment_id} HTTP/1.1

Response

HTTP/1.1 204 No Content

Get a request's timeline

GET /api/requests/{request_id}/timeline

Parameters

Name Type Location Description
request_id   string path The request's public identifier.
q string query Search query used to filter results based on ElasticSearch's query string syntax.
sort string query Sort search results.
size integer query Specify number of items in the results page (default: 10).
page integer query Specify the page of results.
accept string header - application/json (default)
- application/vnd.inveniordm.v1+json (not yet)

Request

GET /api/requests/{request_id}/timeline HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "hits": {
    "hits": [
      {
        "created": "2020-11-27 10:52:23.945755",
        "created_by": {"user": "1"},
        "id": "{comment_id}",
        "links": {
          "self": "{scheme+hostname}/api/requests/{rquest_id}/comments/{comment_id}"
        },
        "payload": {
          "content": "I would use these subject terms to align this record and the other one with others in the community.",
          "format": "html"
        },
        "revision_id": 2,
        "type": "C",
        "updated": "2020-11-27 10:55:23.969244",
      },
      ...
    ],
    "total": 2
  },
  "links": {
    "self": "{scheme+hostname}/api/requests/{request_id}/timeline?page=1&size=25&sort=oldest"
  }
}

Advanced timeline search

The timeline endpoint can be searched, sorted, filtered, paginated etc., like any other InvenioRDM search endpoint.