Page History

...

Another thing to note is that there are Query Parameters that you can tack on to the end of an endpoint to do extra things. The most commonly used one in this API is "?expand". Instead of every API call defaulting to giving you every possible piece of information about it, it only gives a most commonly used set by default and gives the more "expensive" information when you deliberately request it. Each endpoint will provide a list of available expands in the output, but for getting started, you can start with ?expand=all, to make the endpoint provide all of its information (parent objects, metadata, child objects). You can include multiple expands, such as: ?expand=collections,subCommunities.

Pagination

DSpace 6.x supports pagination by allowing two query parameters: limit and offset. Note however that the aggregate results number is not supplied (see DS-3887). Endpoints which return arrays of objects, such as /communities, /collections or /items, are "paginated":  the full list is broken into "pages" which start at offset from the beginning of the list and contain at most limit elements.  By repeated queries you can retrieve any portion of the array or all of it.  The default value of offset  is 0 and the default value of limit is 100.  So, as an example, to retrieve the sixth through tenth elements of the full list of Collections, you could do this:

...

# Can use either POST or GET (POST recommended). Must pass the parameters "email" and "password".
curl -v -X POST --data "email=admin@dspace.org&password=mypass" https://dspace.myu.edu/rest/login

HTTP/1.1 200 OK
Set-Cookie: JSESSIONID=6B98CF8648BCE57DCD99689FE77CB1B8; Path=/rest/; Secure; HttpOnly

curl -v --cookie "JSESSIONID=6B98CF8648BCE57DCD99689FE77CB1B8" https://dspace.myu.edu/rest/status
# This should return <authenticated>true</authenticated>, and information about the authenticated user session

curl -v -L -c cookiejar "https://dspace.myu.edu/rest/shibboleth-login"

curl -v "http://localhost:8080/dspace-rest/status" --cookie "JSESSIONID=0633C6379266A283E53F65DF8EF61AB9"

curl -v -X POST --cookie "JSESSIONID=6B98CF8648BCE57DCD99689FE77CB1B8" https://dspace.myu.edu/rest/logout

curl -v --cookie "JSESSIONID=6B98CF8648BCE57DCD99689FE77CB1B8" https://dspace.myu.edu/rest/status
# This should show <authenticated>false</authenticated>

curl https://demo.dspace.myu.edu.org/rest/test

REST api is running.

curl -v --cookie "JSESSIONID=6B98CF8648BCE57DCD99689FE77CB1B8" https://demo.dspace.myu.eduorg/rest/status

curl -v -H "Accept: application/json" --cookie "JSESSIONID=6B98CF8648BCE57DCD99689FE77CB1B8" https://demo.dspace.myu.eduorg/rest/status

{
  "okay":true,
  "authenticated":true,
  "email":"admin@dspace.org",
  "fullname":"DSpace Administrator",
  "sourceVersion":"6.0",
  "apiVersion":"6"
}

...

For an alternative way to create a Community/Collection hierarchy to the REST API take a look at Importing Community and Collection Hierarchy.

Collections

Collections in DSpace are containers of Items. (ex: Engineering Faculty Publications).

For an alternative way to create a Community/Collection hierarchy to the REST API take a look at Importing Community and Collection Hierarchy.

Items

Items in DSpace represent a "work" and combine metadata and files, known as Bitstreams.

Bitstreams

Bitstreams are files. They have a filename, size (in bytes), and a file format. Typically in DSpace, the Bitstream will the "full text" article, or some other media. Some files are the actual file that was uploaded (tagged with bundleName:ORIGINAL), others are DSpace-generated files that are derivatives or renditions, such as text-extraction, or thumbnails. You can download files/bitstreams. DSpace doesn't really limit the type of files that it takes in, so this could be PDF, JPG, audio, video, zip, or other. Also, the logo for a Collection or a Community, is also a Bitstream..

You can access the parent object of a Bitstream (normally an Item, but possibly a Collection or Community when it is its logo) through: /bitstreams/:bitstreamID?expand=parent

...

In DSpace, Communities, Collections, and Items typically get minted a Handle Identifier. You can reference these objects in the REST API by their handle, as opposed to having to use the internal item-ID.

Hierarchy

Assembling a full representation of the community and collection hierarchy using the communities and collections endpoints can be inefficient. Retrieve a lightweight representation of the nested community and collection hierarchy.  Each node of the hierarchy contains minimal information (id, handle, name).

Schema and Metadata Field Registry

Note: since the schema object contains no data fields, the following method has not been implemented:  PUT PUT /registries/schema/{schema _ id}

Report Tools

Reporting Tools that allow a repository manager to audit a collection for metadata consistency and bitstream consistency.  See REST Based Quality Control Reports for more information or test the Collection Report Tool or Metadata Query Tool on demo.dspace.org.

Model - Object data types

...

{
  "id":456,
  "name":"Reports Community",
  "handle":"10766/10213",
  "type":"community",
  "link":"/rest/communities/456",
  "expand":["parentCommunity","collections","subCommunities","logo","all"],
  "logo":null,
  "parentCommunity":null,
  "copyrightText":"",
  "introductoryText":"",
  "shortDescription":"Collection contains materials pertaining to the Able Family",
  "sidebarText":"",
  "countItems":3,
  "subcommunities":[],
  "collections":[]
}

Collection Object

{
  "id":730,
  "name":"Annual Reports Collection",
  "handle":"10766/10214",
  "type":"collection",
  "link":"/rest/collections/730",
  "expand":["parentCommunityList","parentCommunity","items","license","logo","all"],
  "logo":null,
  "parentCommunity":null,
  "parentCommunityList":[],
  "items":[],
  "license":null,
  "copyrightText":"",
  "introductoryText":"",
  "shortDescription":"",
  "sidebarText":"",
  "numberItems":3
}
}

Item Object

...

{
  "id":14301,
  "name":"2015 Annual Report",
  "handle":"123456789/13470",
  "type":"item",
  "link":"/rest/items/14301",
  "expand":["metadata","parentCollection","parentCollectionList","parentCommunityList","bitstreams","all"],
  "lastModified":"2015-01-12 15:44:12.978",
  "parentCollection":null,
  "parentCollectionList":null,
  "parentCommunityList":null,
  "bitstreams":null,
  "archived":"true",
  "withdrawn":"false"
}

Bitstream Object

{
  "id":47166,
  "name":"appearance and physiology 100 percent copied from wikipedia.pdf",
  "handle":null,
  "type":"bitstream",
  "link":"/rest/bitstreams/47166",
  "expand":["parent","policies","all"],
  "bundleName":"ORIGINAL",
  "description":"","all"]
  "format":"Adobe PDF",
  "mimeType":"application/pdf",
  "sizeBytes":129112,
  "parentObject":null,
  "bundleNameretrieveLink":"ORIGINAL/bitstreams/47166/retrieve",
  "checkSum":{"descriptionvalue":"62778292a3a6dccbe2662a2bfca3b86e",
  "formatcheckSumAlgorithm":"Adobe PDFMD5"},
  "mimeTypesequenceId":"application/pdf",1,
  "policies":null
}

ResourcePolicy Object

{
  "sizeBytesid":129112317127,
  "parentObjectaction":null"READ",
  "retrieveLinkepersonId":"/bitstreams/47166/retrieve"-1,
  "checkSumgroupId":{"value0,
  "resourceId":"62778292a3a6dccbe2662a2bfca3b86e","checkSumAlgorithm47166,
  "resourceType":"MD5bitstream"},
  "sequenceIdrpDescription":1null,
  "policiesrpName":null
}

ResourcePolicy Object

[{ "id":317127,
   "actionrpType":"READTYPE_INHERITED",
   "epersonIdstartDate":-1null,
   "groupId":0,
 endDate":null
}

MetadataEntry Object

{
  "resourceIdkey":47166"dc.description.abstract",
   "resourceTypevalue":"bitstream",
This is the "rpDescription":nulldescription abstract",
   "rpNamelanguage":null, null
}

Schema Object

{
   "rpTypenamespace":"TYPE_INHERITED "example.org/myschema",
   "startDateprefix":null,
   "endDatemyschema":null
}]

...

MetadataField Object

{
  "keydescription" :"dc.description.abstract "myschema test field",
  "valueelement" : "test"This,
 is the"name" description abstract: "myschema.test",
  "languagequalifier": null
}

User Object

{
  "email":"test@dspace.org",
  "password":"pass"
}

Status Object

{
  "okay":true,
  "authenticated":true,
  "email":"test@dspace.org",
  "fullname":"DSpace Test User",
  "token":"6d45daaa-7b02-4ae7-86de-a960838fae5c"
}

...

Usage examples can be found at: https://github.com/BrunoNZ/dspace-rest-requests

A tutorial on item deposits, together with Postman examples is available at