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/{request_id}/comments/{comment_id}"
          "self_html": "{scheme+hostname}/me/requests/{request_id}#commentevent-{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
  },
  "sortBy": "oldest",
  "page": 1,
  "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.

Get the timeline focused on a specific event¶

GET /api/requests/{request_id}/timeline_focused?focus_event_id={event_id}

Same as above, except the page containing the specified event is returned. If the event is not found or does not belong to the request, the first page of events is instead returned. The page number used is returned as the "page" key of the response.

The "self_html" link of the returned items is a pagination-aware deep link that causes the event to be scrolled to and highlighted when the request page is opened (only if the event is of type CommentEventType).

The events are always sorted oldest-to-newest.

Parameters

Name	Type	Location	Description
`request_id`	string	path	The request's public identifier.
`focus_event_id`	string	query	The events's public identifier.
`size`	integer	query	Specify number of items in the results page (default: 10).
`accept`	string	header	- `application/json` (default) - `application/vnd.inveniordm.v1+json` (not yet)

Request

GET /api/requests/{request_id}/timeline_focused?focus_event_id={event_id} 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/{request_id}/comments/{comment_id}"
          "self_html": "{scheme+hostname}/me/requests/{request_id}#commentevent-{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
  },
  "sortBy": "oldest",
  "page": 1,
  "links": {
    "self": "{scheme+hostname}/api/requests/{request_id}/timeline?page=1&size=25&sort=oldest"
  }
}