Old Release

This documentation relates to an old version of DSpace, version 5.x. Looking for another version? See all documentation.

Support for DSpace 5 ended on January 1, 2023.  See Support for DSpace 5 and 6 is ending in 2023

What is DSpace REST API

The REST API module provides a programmatic interface to DSpace Communities, Collections, Items, and Bitstreams.

DSpace 4 introduced the initial REST API, which did not allow for authentication, and provided only READ-ONLY access to publicly accessible Communities, Collections, Items, and Bitstreams. DSpace 5 builds off of this and allows authentication to access restricted content, as well as allowing Create, Edit and Delete on the DSpace Objects. DSpace 5 REST API also provides improved pagination over resources and searching. There has been a minor drift between the DSpace 4 REST API and the DSpace 5 REST API, so client applications will need to be targeted per version.

Installing the REST API

The REST API deploys as a standard webapp for your servlet container / tomcat. For example, depending on how you deploy webapps, one way would be to alter tomcat-home/conf/server.xml and add:

<Context path="/rest"  docBase="/dspace/webapps/rest" />

In DSpace 4, the initial/official Jersey-based REST API was added to DSpace. The DSpace 4 REST API provides READ-ONLY access to DSpace Objects.

In DSpace 5, the REST API adds authentication, allows Creation, Update, and Delete to objects, can access restricted materials if authorized, and it requires SSL.

Disabling SSL

For localhost development purposes, SSL can add additional getting-started difficulty, so security can be disabled. To disable DSpace REST's requirement to require security/ssl, alter [dspace]/webapps/rest/WEB-INF/web.xml or [dspace-source]/dspace-rest/src/main/webapp/WEB-INF/web.xml and comment out the <security-constraint> block, and restart your servlet container. Production usages of the REST API should use SSL, as authentication credentials should not go over the internet unencrypted.

REST Endpoints

The REST API is modeled after the DSpace Objects of Communities, Collections, Items, and Bitstreams. The API is not a straight database schema dump of these entities, but provides some wrapping that makes it easy to follow relationships in the API output.

HTTP Header: Accept

Note: You must set your request header's "Accept" property to either JSON (application/json) or XML (application/xml) depending on the format you prefer to work with. 

Example usage from command line in XML format with pretty printing:

curl -s -H "Accept: application/xml" http://localhost:8080/rest/communities | xmllint --format -

 

Example usage from command line in JSON format with pretty printing:

curl -s -H "Accept: application/json" http://localhost:8080/rest/communities | python -m json.tool

For this documentation, we will assume that the URL to the "REST" webapp will be http://localhost:8080/rest/ for production systems, this address will be slightly different, such as: http://demo.dspace.org/rest/. The path to an endpoint, will go after the /rest/, such as /rest/communities, all-together this is: http://localhost:8080/rest/communities

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 .

Index

MethodEndpointDescription
GET/REST API static documentation page
POST/login

Login to the REST API using a DSpace EPerson (user). It returns a token, that can be used for future authenticated requests (as a value of the rest-dspace-token request header).

Example Request:

curl -H "Content-Type: application/json" --data '{"email":"admin@dspace.org", "password":"dspace"}' http://localhost:8080/rest/login

Example Response:

1febef81-5eb6-4e76-a0ea-a5be245563a5

Invalid email/password combinations will receive an HTTP 403 Forbidden.

The extended tokens are generated and stored in memory, not in the database or on disk. There are no timeouts for these tokens. This means that tokens remain valid as long as DSpace is not restarted. A restart of DSpace will invalidate all extended tokens.

If applications re-use a token over multiple calls, especially if they are spread over a potentially longer time window, it is highly recommended that the /status endpoint is called to guarantee that a specific token is still valid. 

Applications that consume the DSpace REST API have no way of telling when DSpace has been restarted.

In the DSpace logs, calls with invalid tokens can often look like anonymous requests being made.

POST/logout

Logout from the REST API, by providing a header rest-dspace-token. After being posted this token will no longer work.

Example Request:

curl -X POST -H "Content-Type: application/json" -H "rest-dspace-token: 1febef81-5eb6-4e76-a0ea-a5be245563a5" http://localhost:8080/rest/logout

Invalid token will result in HTTP 400 Invalid Request

GET/test

Returns string "REST api is running", for testing that the API is up.

Example Request:

curl http://localhost:8080/rest/test

Example Response:

REST api is running.

GET/status

Receive information about the currently authenticated user token.

Example Request:

curl -X GET -H "Content-Type: application/json" -H "Accept: application/json" -H "rest-dspace-token: f2f478e2-90f2-4e77-a757-4e838ae94154" http://localhost:8080/rest/status

Example Response:
{"okay":true,"authenticated":true,"email":"admin@dspace.org","fullname":"DSpace Administrator","token":"f2f478e2-90f2-4e77-a757-4e838ae94154"}

Communities

Communities in DSpace are used for organization and hierarchy, and are containers that hold sub-Communities and Collections. (ex: Department of Engineering)

  • GET /communities - Returns array of all communities in DSpace.
  • GET /communities/top-communities - Returns array of all top communities in DSpace.
  • GET /communities/{communityId} - Returns community.
  • GET /communities/{communityId}/collections - Returns array of collections of community.
  • GET /communities/{communityId}/communities - Returns array of subcommunities of community.
  • POST /communities - Create new community at top level. You must post community.
  • POST /communities/{communityId}/collections - Create new collections in community. You must post Collection.
  • POST /communities/{communityId}/communities - Create new subcommunity in community. You must post Community.
  • PUT /communities/{communityId} - Update community. You must put Community
  • DELETE /communities/{communityId} - Delete community.
  • DELETE /communities/{communityId}/collections/{collectionId} - Delete collection in community.
  • DELETE /communities/{communityId}/communities/{communityId2} - Delete subcommunity in community.

Collections

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

  • GET /collections - Return all collections of DSpace in array. Use the limit parameter to control items per response (default 100) and offset for paging.
  • GET /collections/{collectionId} - Return collection with id.
  • GET /collections/{collectionId}/items - Return all items of collection. Use the limit parameter to control items per response (default 100) and offset for paging.
  • POST /collections/{collectionId}/items - Create posted item in collection. You must post an Item
  • POST /collections/find-collection - Find collection by passed name.
  • PUT /collections/{collectionId} - Update collection. You must put Collection.
  • DELETE /collections/{collectionId} - Delete collection from DSpace.
  • DELETE /collections/{collectionId}/items/{itemId} - Delete item in collection.

Items

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

  • GET /items - Return list of items.
  • GET /items/{item id} - Return item.
  • GET /items/{item id}/metadata - Return item metadata.
  • GET /items/{item id}/bitstreams - Return item bitstreams.  Use the limit parameter to control items per response (default 100) and offset for paging.
  • POST /items/find-by-metadata-field - Find items by metadata entry. You must post a MetadataEntry.  Unable to locate Jira server for this macro. It may be due to Application Link configuration.
  • POST /items/{item id}/metadata - Add metadata to item. You must post an array of MetadataEntry
  • POST /items/{item id}/bitstreams - Add bitstream to item. You must post a Bitstream
  • PUT /items/{item id}/metadata - Update metadata in item. You must put a MetadataEntry
  • DELETE /items/{item id} - Delete item.
  • DELETE /items/{item id}/metadata - Clear item metadata.
  • DELETE /items/{item id}/bitstreams/{bitstream id} - Delete item bitstream.

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.

  • GET /bitstreams - Return all bitstreams in DSpace.  Use the limit parameter to control items per response (default 100) and offset for paging.
  • GET /bitstreams/{bitstream id} - Return bitstream.
  • GET /bitstreams/{bitstream id}/policy - Return bitstream policies.
  • GET /bitstreams/{bitstream id}/retrieve - Return data of bitstream.
  • POST /bitstreams/{bitstream id}/policy - Add policy to item. You must post a ResourcePolicy
  • PUT /bitstreams/{bitstream id}/data - Update data/file of bitstream. You must put the data
  • PUT /bitstreams/{bitstream id} - Update metadata of bitstream. You must put a Bitstream, does not alter the file/data
  • DELETE /bitstreams/{bitstream id} - Delete bitstream from DSpace.
  • DELETE /bitstreams/{bitstream id}/policy/{policy_id} - Delete bitstream policy.

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

As the documentation may state "You must post a ResourcePolicy" or some other object type, this means that there is a structure of data types, that your XML or JSON must be of type, when it is posted in the body.


Handle

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.

  • GET /handle/{handle-prefix}/{handle-suffix} - Returns a Community, Collection, or Item object that matches that handle.

Model - Object data types

Here are all of the data types, not all fields are necessary or supported when posting/putting content, but the output contains this information:

Community Object

{"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":"","format":"Adobe PDF","mimeType":"application/pdf","sizeBytes":129112,"parentObject":null,"retrieveLink":"/bitstreams/47166/retrieve","checkSum":{"value":"62778292a3a6dccbe2662a2bfca3b86e","checkSumAlgorithm":"MD5"},"sequenceId":1,"policies":null}

ResourcePolicy Object

[{"id":317127,"action":"READ","epersonId":-1,"groupId":0,"resourceId":47166,"resourceType":"bitstream","rpDescription":null,"rpName":null,"rpType":"TYPE_INHERITED","startDate":null,"endDate":null}]

MetadataEntry Object

{"key":"dc.description.abstract", "value":"This is the description abstract", "language": 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"}


Introduction to Jersey for developers

The REST API for DSpace is implemented using Jersey, the reference implementation of the Java standard for building RESTful Web Services (JAX-RS 1). That means this API should be easier to expand and maintain than other API approaches, as this approach has been widely adopted in the industry. If this client documentation does not fully answer about how an endpoint works, it is helpful to look directly at the Java REST API code, to see how it is implemented. The code typically has required parameters, optional parameters, and indicates the type of data that will be responded.

There was no central ProviderRegistry that you have to declare your path. Instead, the code is driven by annotations, here is a list of annotations used in the code for CommunitiesResource.java:

  • @Path("/communities"), which then allows it to be routed to http://localhost:8080/communities, this is then the base path for all the requests within this class.

  • @GET, which indicates that this method responds to GET http requests

  • @POST, which indicates that this method responds to POST http requests
  • @PUT, which indicates that this method responds to PUT http requests
  • @DELETE, which indicates that this method responds to DELETE http requests
  • @Path("/{community_id}"), the path is appended to the class level @Path above, this one uses a variable {community_id}. The total endpoint would be http://localhost:8080/rest/communities/123, where 123 is the ID.

  • @Consumes({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML }), this indicates that this request expects input of either JSON or XML. Another endpoint accepts HTML input.

  • @PathParam("community_id") Integer communityId, this maps the path placeholder variable {community_id} to Java int communityID
  • @QueryParam("userIP") String user_ip, this maps a query param like ?userIP=8.8.4.4 to Java String user_id variable, and user_id == "8.8.4.4"


Configuration for DSpace REST

Propertystats
Example Valuetrue
Informational NoteBoolean value indicates whether statistics should be recorded for access via the REST API; Defaults to 'false'.

Recording Proxy Access by Tools

For the purpose of more accurate statistics, a web-based tool may specify who is using it, by adding parameters to the request:

http://localhost:8080/rest/items/:ID?userIP=ip&userAgent=userAgent&xforwardedfor=xforwardedfor

If no parameters are given, the details of the HTTP request's sender are used in statistics. This enables tools to record the details of their user rather than themselves.

Additional Information

Additional information can be found in the README for dspace-rest, and in the GitHub Pull Request for DSpace REST (Jersey).

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

  • No labels

27 Comments

  1. Ivan Masár

    The section describing how to create new Jersey endpoints doesn't really belong to User Docs. We don't yet have a separate section in the official docs for Developer Docs, but we should create one. Also, what about describing this in JavaDoc?

  2. Kostas Stamatis

    We should also add some documentation on the following:

    1) How someone can use more that one expands in the same request (ie: concatenation with a comma)

    2) Examples of responses in both formats. What the user should expect. Are the output fields in their place when no value applies for them or the are ommitted in the output?

    3) New config file (rest.cfg) and the statistics option

     

    1. Ivan Masár

      ad 2): also error reporting - what should user expect in case of error (errorneous input, server errors)

      4) deploying the REST webapp (IMHO we should encourage people to deploy it by default so that we can later rely on it being present and avoid duplicating functionality like e.g. RSS that is common to both UIs by putting it into REST instead), controlling access to the REST endpoint

      1. Peter Dietz

        (In response to Ivan's comments)

        2) This isn't settled ground yet for error reporting, but you can expect to trust your HTTP Status Codes, especially since I haven't produce pretty/json/xml error responses, mostly just a stack-trace in HTML, which is jersey default WebAppException. I think we're throwing:

        • 200-OK, 
        • 401 (or 403 not sure...)-Unauthorized, can't see this restricted content, 
        • 404 - Object doesn't exist, 
        • 406-API can't serialize in the requested format, 
        • 500-InternalServerError

        4) I've added a small section on example of how to add a context for /rest. I think refactoring internal DSpace logic to make use of REST (for search / rss / etc) is premature. To make the RSS go through REST makes the UI's make a dependency on REST, which I'm not ready to do, in this initial release.

        We will want to refactor internal DSpace business logic to simplify how each webapp (JSPUI, XMLUI, OAI, LNI, ..., REST) does certain things. i.e. Move some of that bloated logic out of webapp, and into central DSpace-Core. Once the refactor goes through, then we can determine if things get "outsourced" to REST API.

    2. Peter Dietz

      1) I've added an example of multiple expands with a comma.

      2) Haven't added examples of response data yet, but there are tools designed exactly for this purpose. Bram has showed me an example of "API DOCUMENTATION" from miredot, and Bill McKinney has generated swagger documentation for a different flavor of DSpace Jersey Rest. So, at this point, I'm not sure how much should be in DSpace Documentation, vs how much should be in a DSpace Developer Documentation, if there were such a thing...

      3) I have just added rest.cfg and statistics information, from Anja's latest PR.

  3. Tomasz Sawicki

    In order to set name and description of bitstream when creating it you have to put them in query params:

    POST /{item_id}/bitstreams?name=name_of_file&description=description_of_file

  4. Christian Velez

    Is the only way to change the name on a newly created Item is to create it and then add the dc.title metadata entry? This seems unnatural, since in the creation of communities and collections the name of the object can be specified in the body of the POST request (by supplying the "name" entry in the json). 

    Also, in the documentation of the MetadataEntry object, the key to specify the language is said to be "lang" when in reality the REST API accepts the key "language" to change the entry's language. 

    Thanks in advance. 

    1. Bruno Nocera Zanette

      Christian,


      It's possible to create items with only one request. It's quite simple. You just have to create a list of metadata and send it to REST-API. The format of this request is on the bottom of this message. Bitstreams, on the hand, are a little bit trickier, but it's also possible. The only difference is that you have to append the information to the URL like Tomasz Sawicki showed, and not send it on a JSON or XML.

      I was planning to update this doc with the informations that i've gathered but i'm lacking of time. However, i've created some scripts to test it that contains all current available requests that may be useful to understand how the requests works. You can find the code at:
      https://github.com/BrunoNZ/dspace-rest-requests


      I've also created a RubyGem to interact with Rest-Api, that you can find here:
      https://gitlab.c3sl.ufpr.br/bnzanette/dspace-rest-client
      It's still early on development but already works pretty well, and may also be useful to use as basis to create something similar using other languages.

      I hope this helps you!!

      Cheers!!

       

      {"metadata":[
{
"key": "dc.contributor.author",
"value": "LAST, FIRST"
},
{
"key": "dc.description",
"language": "en_US",
"value": "DESCRIPTION"
},
{
"key": "dc.description.abstract",
"language": "en_US",
"value": "ABSTRACT"
},
{
"key": "dc.title",
"language": "pt_BR",
"value": "TESTE"
}
]}

      1. Christian Velez

        Bruno, 

        Thanks for the fast response! I'm creating too a lib for interacting with the REST API, only difference is it's in PHP. We plan to develop it in-house first and then release it as open source. Will be incorporating this changes in these days, again, thanks for the response. It was really helpful!

  5. Patrick Murray-John

    Hi,

    I'm having some trouble reconciling parts of the REST responses, both within one response and, possibly between the 4.x and 5.x versions.

    The trouble happens when following 'link' and 'retrieveLink' in bitstream data. From the demo server, I get something like this. 'link' has "/RESTapi" prefixed, where I would have expected just "/rest" so I could follow it directly without changing the string. 'retrieveLink', on the other hand, doesn't prefix at all, so I need to add the "/rest" when following the link.

        {
          "id": 44,
          "name": "LIS 403 -1 Notes.pdf",
          "handle": null,
          "type": "bitstream",
          "link": "/RESTapi/bitstreams/44",
          "expand": [
            "parent",
            "policies",
            "all"
          ],
          "bundleName": "ORIGINAL",
          "description": null,
          "format": "Adobe PDF",
          "mimeType": "application/pdf",
          "sizeBytes": 1803525,
          "parentObject": null,
          "retrieveLink": "/bitstreams/44/retrieve",
          "checkSum": {
            "value": "16e430831d5e28e6ae84beb3f96b9587",
            "checkSumAlgorithm": "MD5"
          }

    A slightly different example comes from my IR, which might be on 4.x. Here, 'link' has '/rest' at the beginning as expected, but similarly does not include it in 'retrieveLink'

        {

          "id": 22492,

          "name": "0.html",

          "handle": null,

          "type": "bitstream",

          "link": "/rest/bitstreams/22492",

          "expand": [

            "parent",

            "all"

          ],

          "bundleName": "ORIGINAL",

          "description": null,

          "format": "HTML",

          "mimeType": "text/html",

          "sizeBytes": 4065,

          "parentObject": null,

          "retrieveLink": "/bitstreams/22492/retrieve",

          "checkSum": {

            "value": "7c3c1bf1a0c3b3c7639a051dd9f6b9e4",

            "checkSumAlgorithm": "MD5"

          },

          "sequenceId": 1

        }

    So, my questions are:

    1. Should the link and retrieveLink really be things that I can directly follow, without adjusting the strings?
    2. If this is a difference in the versions, and if I will need to adjust the strings, is there a way to know what version of the API I'm hitting so I know what string manipulations to do?

    Many thanks for help and guidance,

    Patrick

  6. Bruno Nocera Zanette

    Patrick,

    1)
    I haven't used "link" field yet, so i don't know what is its purpose. I suppose it's a link for the bitstream itself, the same link used to make the request. In this case /RESTapi should be adjusted to <dspace_url>/rest/bitstream/<ID>. I believe that "/RESTapi" is a mistake.  
    The "retrieveLink", on the other hand, is a functional endpoint for REST api, being only necessary to append <dspaceurl> to it.  It's used to download the requested bitstream.

    2)
    I don't think there is a request that returns REST's api version. That's actually something that i haven't thought about and that is very important. Right now, i think the only way to identify which version you are dealing with is to process the "homepage" that is quite different between the two versions. Also, you need to be careful about the requests and responses that may be different too. How many dspace's instances are you planning to deal with at the same time?

  7. Patrick Murray-John

    Thanks. "/RESTapi" did look like a mistake. If my IR's example is from an older version, it seems like for all those `link`s, it should probably follow that pattern and include "/rest". The `link` data appears in lots of places (on items, collections, etc.), and does look like the endpoints. What I get with "retrieveLink", though doesn't quite work the same way. That is, if I have $dspaceurl = "http://ebot.gmu.edu", then for all the `link`s I can just append the value to get something like "http://ebot.gmu.edu/rest/items/1" because the value in the `link` includes '/rest'. The way retrieveLink is structured is different, though, and doesn't include the '/rest' at the beginning, and so the pattern doesn't actually give the REST endpoint. It's a tiny switch in the code, but might be nicer to have it all work the same way.

    This is for a module for the next incarnation of the Omeka web publishing platform, for institutions that want to import parts of their IRs into it. So, conceivably, the plugin would need to be able to handle different versions of dspace across dozens of institutions.

    Thanks again!

     

  8. Ivan Masár

    HTTP response 415 "Unsupported Media Type" might mean that you forgot to add the "Content-Type: application/json" request header to a POST or PUT request.

  9. WangYundong

    Hi,

    How can I call the url "localhost:8080/rest/items/find-by-metadata-field"? I don't know how to write params.Can who share a demo?

    Thank you!

     

     

    1. Bruno Nocera Zanette

      WangYundong,

      You need to send a JSON/XML containing a metadata's description along with the POST request.

      Example:

      ----------------------------------------------------------------------------------------------------

      $ curl -k -4 -H "accept: application/json" -H "Content-Type: application/json" -X POST "https://demo.dspace.org/rest/items/find-by-metadata-field" -d '{"key": "dc.title","value": "Test Webpage","language": "en_US"}'

      ----------------------------------------------------------------------------------------------------

      This command will return the following answer:

      ----------------------------------------------------------------------------------------------------
      [{"id":1,"name":"Test Webpage","handle":"10673/4","type":"item","link":"/RESTapi/items/1","expand":["metadata","parentCollection","parentCollectionList","parentCommunityList","bitstreams","all"],"lastModified":"2015-04-12 02:00:18.24","parentCollection":null,"parentCollectionList":null,"parentCommunityList":null,"bitstreams":null,"archived":"true","withdrawn":"false"}]

      ----------------------------------------------------------------------------------------------------

      The problem is that this query is extremely strict. All the 3 fields must be defined and and all 3 must match exactly with the result, and only one metadata instance is accepted. For instance, if you set "value" to only "Test" the query will return blank, and if you add another metadata instance it will be ignored by REST. If you need a broader query i suggest you to take a look at SOLR, or implementing a new Endpoint on REST API.

      That's it. I hope it helps!!

      1. WangYundong

        Bruno Nocera Zanette:

        Thank you for your reply.I have got it yesterday afternoon.It's just because of the problem of the sql sentence of the "find-by-metadata-field"'s method called "findItemsByMetadataField" in source code.

        I have changed the sql sentence" String sql = "SELECT ITEM_ID, TEXT_VALUE, TEXT_LANG, SHORT_ID, ELEMENT, QUALIFIER " " to "String sql = "SELECT RESOURCE_ID AS ITEM_ID, TEXT_VALUE, TEXT_LANG, SHORT_ID, ELEMENT, QUALIFIER "".And then,I Installed the dspace source code secondly.And It's OK.Absolutely,it's text should be json/xml.

        Thank you all the same.

  10. Luis Carlos Alvarez Fernández

    Hello everyone. I am a developer at the University of Informatic Sciences in Havana, Cuba. Here are developing a demo to deposit items in DSpace, based on document types. There is doubt: When I deposit a document using the REST API, this document goes through the review process associated with the collection where it is deposited, or is incorporated directly into DSpace? Greetings.

  11. Frau Hildebraun

    Hello everyone!

    I create item via endpoint  /collections/{collectionId}/items . Now I want to upload file for this item via endpoint  /items/{item id}/bitstreams. But file is created without name (file.pdf), so I can't to open it in browser.

    Please, does anybody can show example how right do this (curl or php)? 

    Thank you! 

    1. Peter Dietz

      @ Frau Hildebraun, Is your question about how to set the filename, or how to view the bitstream? To view the bitstream, do a GET to /bitstreams/<id>/retrieve. https://demo.dspace.org/rest/bitstreams/203/retrieve, Viewing that in Chrome opens the PDF in the browser. There could be a file size limit, where your browser will download the file as opposed to displaying it inline. (Also, the demo instance resets weekly, so that link will break in the future). 

      Some operations such as uploading, and setting metadata, will require multiple API calls. So you may need to upload a bitstream, and then set its metadata. (I'll have to double check).

      There are also some curl examples: https://github.com/DSpace-Labs/dspace-rest-requests

       

      @ Luis Carlos Alvarez Fernández, It appears that the REST API will directly submit the item to the collection, bypassing the workflow. That is how the command-line import process works, skipping the workflow by default, but I believe the command-line import process also has an option to allow the item to enter the workflow if a workflow exists for that collection. The REST API currently does not have a way to have an item enter the workflow if a workflow exists. This would be a good feature to implement, if someone has the time / interest.

      1. Frau Hildebraun

        Thank you Peter for your attention! I asked about  how to set the filename.

        If I understood correctly, I have to call API 3 times: 1. create item via endpoint  /collections/{collectionId}/items. 2. upload file via endpoint  /items/{item id}/bitstreams. 3. set filename via endpoint  /bitstreams/{bitstream id} .

        Am I right?

        And what about this method https://jspace.atlassian.net/wiki/display/DSPACEAPI/POST_items ? Does it require multiple API calls? And what endpoint is needed for it?

        Thank you!

        1. Bruno Nocera Zanette

          Frau Hildebraun,

          I just learned how to pass the filename parameter along with the file. All you have to do is to add "?name=filename.ext&description=description" to URL.

          For example, using cURL, it would look something like this:
          curl -k -4 \
            -H "rest-dspace-token: 57f29e49-4758-4bc4-9a73-13cdbab90e19" \
            -H "accept: application/json" \
            -X POST "https://demo.dspace.org/rest/items/1/bitstreams?name=filename.ext&description=description" \
            -T "./path/to/filename.ext"

          But, you still have to use at least 2 steps to upload the bitstream (Create Item and Upload Bitstream).

          I'll update the git project that Peter mentioned with those changes.

          Cheers!

          1. Frau Hildebraun

            Thank you very much!!!

  12. Patrick Murray-John

    How do I page through results? I have a collection with 129 items, but the json array returned contains only 100. Thanks!

    1. Ivan Masár

      Use the limit and offset parameters for paging. I'll add them to this wiki page.

      http://demo.dspace.org/javadocs/5/apidocs/org/dspace/rest/ItemsResource.html#getItems(java.lang.String,%20java.lang.Integer,%20java.lang.Integer,%20java.lang.String,%20java.lang.String,%20java.lang.String,%20javax.ws.rs.core.HttpHeaders,%20javax.servlet.http.HttpServletRequest)

      1. Patrick Murray-John

        Thanks. However, `offset` doesn't seem to be working as expected – no matter the offset, I get the same set of results back

        https://demo.dspace.org/rest/collections/19/items?limit=5&offset=10

        1. Peter Dietz

          Let us know (in the JIRA or PR or here) if  Unable to locate Jira server for this macro. It may be due to Application Link configuration.  or https://github.com/DSpace/DSpace/pull/992 are related and/or solve the problem you encounter with offset.

          1. Patrick Murray-John

            Thanks much. They certainly look like the same issue I'm having. I don't have my own installation of DSpace to try the PR, though, so I'll probably have to wait for an update to our library's installation to test it directly.

All content on the LYRASIS Wiki is licensed under the CC BY (Attribution) license, unless otherwise noted.