REST data services

A group of Restspace services act like REST databases, whether for binary, text or JSON data. These follow similar principles in how they operate. They can all store data items on any path they control. HTTP verbs generally work as below:

  • GET: read the resource and return in the response body, the Content Type header indicating the type of resource read. Final slash is signficant, see below.
  • PUT: write the resource. Returns HTTP status 201 if this creates a new resource or 200 if it updates an existing one.
  • POST: same as PUT
  • DELETE: deletes the resource.
  • HEAD: this does exactly the same as GET but doesn't return a response body, only headers.
  • OPTIONS: always succeeds and returns the security headers in force.

REST data services allow for reading a listing of directory contents by doing a GET request for a url such as /myservice/mydirectory/ with a final slash. This returns a JSON response, an object with the properties below:

  • path: the service path of the requested directory (in this example, /mydirectory)
  • files: array of objects describing files and subdirectories in the directory. Each object has at least the property name for the name of the item. Subdirectory names can be distinguished by a trailing slash.
  • mimeTypes: array of the mime types which can exist in this directory (as data).

Directory listing requests can have a couple of special query string flags:

  • ?recursive: read recursively into directories and list all the files found
  • ?filenames: change the output format to just an array of filenames

If you request a resource without supplying an extension, the REST data service will have a default mime type whose file extension it will append internally.

In the configuration of this service, you must supply the path in your file storage system to which the data will be stored using the adapter property and the filePathRoot subproperty, like this:

{ ...
 adapter: {
   filePathRoot: "/files/general"
 }
 ...
}

which would store all files to a path within the file storage got by appending the service path of the item to /files/general.