DSpace PHP REST

This middleware exposes public information from a DSpace repository. Requires PHP 8. No PHP REST API framework is used.

The API endpoints retrieve Community, Collection, Item and Bitstream information from the DSpace REST API and return simplified responses. The responses contain only "essential" information about DSpace objects. The goal is to provide an easy-to-use service for constructing websites, omitting the more extensive information needed to create a fully-featured DSpace user interface.

The DSpaceDataService implementation can also be included in a PHP webpage and used to access DSpace content without using the PHP API.

Contents:

Usage
Endpoints
Pagination
Configuration

Usage

Simple example: copy the contents of the source directory to the web server and use this URL:

http://localhost/example/index.php/api/endpoints

Apache configuration example: To simplify the url and get rid of index.php you can add the following to your Apache configuration for the base directory. This example assumes the base directory for the application is /example and redirects all requests to index.php.

RewriteEngine On
RewriteBase /example
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^(.+)$ index.php [QSA,L]

Here's the new request URL:

http://localhost/example/api/endpoints

If it's a production site, you should probably add a cache-control header to your Apache config as well.

Endpoints

/api/endpoints

List of endpoints.

/api/toplevel

Gets information about the top-level communities (sections)

Sample JSON response:

{
  "pagination": {
    "next": [
      {
        "page": 1,
        "size": 5
      }
    ],
    "prev": [ ]
  },
  "objects": {
    "Section One": {
      "name": "Section One",
      "uuid": "602c3c60-55f8-4e2f-98bb-1f280a818bfe",
      "logo": "/images/default.jpeg",
      "collectionCount": "0",
      "subsectionCount": "4"
    },
    "Section Two": {
      "name": "Section Two",
      "uuid": "ce894cbb-65eb-4642-83e7-81f2fda2cec0",
      "logo": "http://localhost:8080/server/api/core/bitstreams/ccd3874b-2b68-476b-bf21-09365f866b76/content",
      "collectionCount": "1",
      "subsectionCount": "1"
    }
  },
  "count": "10"
}

/api/sections/<:uuid>

Gets information about a specific community (section).

###Parameters:

name: uuid
in: path
required: true
description: The DSpace uuid of the community (section)

Sample JSON response:

{
   "name": "Section Name",
   "uuid": "602c3c60-55f8-4e2f-98bb-1f280a818bfe",
   "logo": "/images/default.jpeg",
   "collectionCount": "0",
   "subsectionCount": "4"
}

/api/sections/<:uuid>/subsections

Gets list of subsections within the section with the provided uuid.

Parameters

name: uuid
in: path
required: true
description: The DSpace uuid of the community (section)

name: page
in: query
required: false
description: The current page in pagination (default = 0)

name: size
in: query
required: false
description: The current page size used for pagination (default defined in Configuration).

Sample JSON response:

{
  "pagination": {
    "next": {
      "page": "1",
      "pageSize": "2"
    },
    "prev": {}
  },
  "objects": {
    "Section One": {
      "name": "Section One",
      "uuid": "210d5023-daa6-4e82-a62b-2749cfd4c61d",
      "logo": "http://localhost:8080/server/api/core/bitstreams/04062743-0e22-48cd-967c-239d075000ea/content",
      "collectionCount": "1",
      "subsectionCount": "1"
    },
    "Section Two": {
      "name": "Section Two",
      "uuid": "35eaa237-3e86-40a2-9973-de61914ac080",
      "logo": "http://localhost:8080/server/api/core/bitstreams/ccd3874b-2b68-476b-bf21-09365f866b76/content",
      "collectionCount": "0",
      "subsectionCount": "4"
    } 
  },
  "count": "4"
}

/api/sections/<:uuid>/collections

List of the collections within the section with the provided uuid.

Parameters

name: uuid
in: path
required: true
description: The DSpace uuid of the community (section)

name: page
in: query
required: false
description: The current page in pagination (default = 0)

name: size
in: query
required: false
description: The current page size used for pagination (default defined in Configuration).

Sample JSON response:

{
  "pagination": {
    "next": [ ],
    "prev": [ ]
  },
  "objects": [
    {
      "name": "Collection One",
      "uuid": "0b6eba01-5bef-440f-a950-b29dd37db50",
      "description": "Collection One full description.",
      "shortDescription": "Collection One short description",
      "logo": "http://localhost:8080/server/api/core/bitstreams/291c1a8c-3475-4194-851c-6639f02a8331/content",
      "itemCount": "3"
    },
    {
      "name": "Collection Two",
      "uuid": "1eb8d02b-3cf7-459c-a37f-dc2122a75a1f",
      "description": "Collection Two full description..",
      "shortDescription": "Collection Two brief description.",
      "logo": "http://localhost:8080/server/api/core/bitstreams/00a76cd4-08dc-4c53-96f8-2111c110c6b4/content", 
      "itemCount": "0"
    }
  ],
  "count": "2"
}

/api/collections/<:uuid>

Information about a specific DSpace collection. Includes the number of items in the collection.

Parameters

name: uuid
in: path
required: true
description: The DSpace uuid of the collection.

Sample JSON response:

{
  "name": "Collection",
  "uuid": "0b6eba01-5bef-440f-a950-b29dd37db505",
  "description": "This is the description of the DSpace collection.",
  "shortDescription": "This is the short description of the DSpace collection.",
  "logo": "http://localhost:8080/server/api/core/bitstreams/291c1a8c-3475-4194-851c-6639f02a8331/content",
  "itemCount": 3
}

/api/collections/<:uuid>/items

List of items within a specific DSpace collection with the provided uuid.

Parameters

name: uuid
in: path
required: true
description: The DSpace uuid of the community (section)

name: page
in: query
required: false
description: The current page in pagination (default = 0)

name: size
in: query
required: false
description: The current page size used for pagination (default defined in Configuration).

Sample JSON Response:

{
  "pagination": {
    "next": [ ],
    "prev": [ {
        "page": "0",
        "pageSize": "2"
      }
    ]
  }, 
  "objects": [
    {
      "name": "Item One Title", 
      "uuid": "b30f3383-8653-4114-abaa-b642a6e535a1", 
      "metadata": {
        "title": "Item One Title",
        "creator": "John Doe",
        "date": "2023",
        "description": "Description of item."
      },
      "owningCollection": "http://localhost:8080/server/api/core/items/b30f3383-8653-4114-abaa-b642a6e535a1/owningCollection", 
      "logo": "http://localhost:8080/server/api/core/bitstreams/3a869688-3cfe-4074-95f5-706749f8e9d0/content"
    }, 
    {
      "name": "Item Two Title", 
      "uuid": "b1b4aff9-1572-4e4d-be4d-a6216cc52d3f",
      "metadata": {
        "title": "Item Two Title",
        "creator": "Julie Doe",
        "date": "2023",
        "description": "Description of item."
      },
      "owningCollection": {
        "href": "http://localhost:8080/server/api/core/items/b30f3383-8653-4114-abaa-b642a6e535a1/owningCollection"
      },
      "logo": "http://localhost:8080/server/api/core/bitstreams/1008de2c-069f-4a01-8ef5-9b7fe0df1e92/content"
    }
  ], 
  "count": "4"
}

/api/items/<:uuid>

Information about a specific DSpace item.

Parameters

name: uuid
in: path
required: true
description: The DSpace uuid of the item.

Sample JSON Response:

{
  "name":"Sample Item",
  "uuid":"b30f3383-8653-4114-abaa-b642a6e535a1",
  "metadata" :{
    "description": "Description of item ...</p>",
    "creator": "Jane Doe",
    "date": "2023",
    "rights": "Educational use allowed.",
    "rights.uri": "https://rights.edu"
  },
  "owningCollection":{
    "href": "http://localhost:8080/server/api/core/collections/0b6eba01-5bef-440f-a950-b29dd37db505",
    "name": "Owning Collection Name",
    "uuid": "0b6eba01-5bef-440f-a950-b29dd37db505"
  },
  "thumbnail":"http:\/\/localhost:8080\/server\/api\/core\/bitstreams\/3a869688-3cfe-4074-95f5-706749f8e9d0\/content"
}

/api/items/<:uuid>/files

Gets list of files for the item with the provided DSpace uuid.

Parameters

name: uuid
in: path
required: true
description: The DSpace uuid of the item.

name: bundle
in: query
required: false
description: Name of alternate bundle for images.

Note that if thumbnail images for the individual files don't exist in DSpace a default image will be used.

Sample JSON response:

{
  "pagination":[],
  "objects": [
    {
      "name": "roger-11.jpeg",
      "href": "http:\/\/localhost:8080\/server\/api\/core\/bitstreams\/1ba87266-e790-475a-b5ea-d51b2b5b5ae0\/content",
      "uuid": "1ba87266-e790-475a-b5ea-d51b2b5b5ae0",
      "thumbnail": "http:\/\/localhost:8080\/server\/api\/core\/bitstreams\/1ba87266-e790-475a-b5ea-d51b2b5b5ae0\/content",
      "mimetype": "image\/jpeg",
      "metadata": {
        "title": "roger-11.jpeg",
        "label": "The best photo.",
        "medium": "Digital",
        "dimensions": "13\" x 17\"",
        "subject": "surrealism",
        "description": "Image 1",
        "type": "Illustration",
        "rights": "Educational use allowed.",
        "rights.uri": "https://rights.edu"
      } 
    }], 
  "count": "1"
}

/api/files/<:uuid>

Information about the file with the provided DSpace uuid.

Parameters

name: uuid
in: path
required: true
description: The DSpace uuid of the file.

Sample JSON response:

{
  "name":"roger-10.jpeg",
  "href":"http:\/\/localhost:8080\/server\/api\/core\/bitstreams\/a6c0a357-8901-45fd-9a3d-4616233106f8\/content",
  "uuid":"a6c0a357-8901-45fd-9a3d-4616233106f8",
  "thumbnail":"http:\/\/localhost:8080\/server\/api\/core\/bitstreams\/a6c0a357-8901-45fd-9a3d-4616233106f8\/content",
  "mimetype":"image\/jpeg",
  "metadata": {
    "title":"roger-10.jpeg",
    "label":"The View",
    "medium":"Digital",
    "dimensions":"13\" x 17\"",
    "subject":"cosmology",
    "description":"Photo of universe",
    "type":"Illustration"
  }
}

/api/search

Search for DSpace items, collections and communities (sections). Response includes the type of DSpace object (item, collection, or community).

Parameters

name: query
in: query
required: true
description: The query term

name: scope
in: query
required: true
description: The query scope (collection or section uuid)

name: page
in: query
required: false
description: The current page in pagination (default = 0)

name: size
in: query
required: false
description: The current page size used for pagination (default defined in Configuration).

Sample JSON response:

{
  "pagination": {
    "next": [ ],
    "prev": [ ]
  },
  "objects": [
    {
      "name": "Jane's Thesis Spring 2023",
      "uuid": "ae44806f-b854-4de9-8113-100494d81997",
      "type": "item",
      "metadata": {
       "title": "My Thesis",
       "creator": "Jane Doe",
       "description": "Description of my thesis.",
       "date": "2023"
      },
      "thumbnail": {
        "name": "jane-1.jpeg.jpg",
        "href": "http://localhost:8080/server/api/core/bitstreams/ecd9b20c-86d7-4a6a-b0bf-306cae8d3049/content"
      }
    },
    {
      "name": "Thesis",
      "uuid": "35eaa237-3e86-40a2-9973-de61914ac080",
      "type": "community",
      "metadata": {
        "title": "Thesis",
        "description": "Section Name description ..."
      }
    }
  ],
  "count": "2"
}

/api/collections/<:uuid>/itemcount

Returns the count of items for the collection with the provided uuid. This is a special endpoint that can be used to request counts asynchronously. See Configuration parameter "retrieveItemCounts".

Parameters

name: uuid
in: path
required: true
description: The DSpace uuid of the collection.

Sample JSON response:

"180"

Pagination

List endpoints accept pagination parameters.

This is a sample pagination element from a response. Both next and previous results are available.

  "pagination": {
    "next": [ 
       "page" : "2",
       "size": "20"
       ]
    "prev": [ 
    "page" : "0",
     "size": "20"
     ]
  }

You can use this information to make next and previous page requests.

For example, to request the next page of search results:

http://localhost/api/search?query=test+query&page=2&size=20

Configuration

/**
* Base url of DSpace REST API
*/
"base"=>"http://localhost:8080/server/api",
/**
* The default DSpace scope. Used for search.
*/
"scope" => "602c3c60-55f8-4e2f-98bb-1f280a818bfe",
/**
* The maximum number of items returned in requests for DSpace objects (e.g. Items, Collections).
* Currently this class does not support pagination.
*/
"defaultPageSize" => 40,
/**
* The maximum number of embedded bitstreams (e.g. images) returned when retrieving images.
* The bitstreams are retrieved as embedded elements in the bundle. Pagination is not currently
* supported by this application.
*/
"defaultEmbeddedBitstreamParam" => 60,
/**
* Default image used in no thumbnail is available.
*/
"defaultThumbnail" => "/mimi/images/pnca_mimi_default.jpeg",
/**
* Retrieve item counts for collections. There may be a performance hit when set to true.
* Item counts can also be retrieved asynchronously via the <code>api/collections/<:uuid>/itemcount</code>
* endpoint.
*/
"retrieveItemCounts" => true,
/**
* When true all DSpace API requests and responses are written to the log file.
* This is verbose. The value should be false when not actively debugging or developing.
*/
"debug" => false

hatfieldlibrary/dspace-php-rest

DSpace PHP REST

Usage

Endpoints

/api/endpoints

/api/toplevel

/api/sections/<:uuid>

/api/sections/<:uuid>/subsections

Parameters

/api/sections/<:uuid>/collections

Parameters

/api/collections/<:uuid>

Parameters

/api/collections/<:uuid>/items

Parameters

/api/items/<:uuid>

Parameters

/api/items/<:uuid>/files

Parameters

/api/files/<:uuid>

Parameters

/api/search

Parameters

/api/collections/<:uuid>/itemcount

Parameters

Pagination

Configuration