Pluggable Remote API Architecture
From ResourceSpace Documentation Wiki
Contents |
Introduction
ResourceSpace Digital Asset Management system is a flexible and customizable web-based, open source repository for images, videos, audio, other filetypes and associated data. As such it serves well as a backend to other systems which would like to use that data, such as Web Content Management Systems, E-commerce systems, and mobile apps.
The ResourceSpace Remote API allows you to securely access and modify information in a ResourceSpace installation via HTTP (preferably HTTPS) requests.
This document assumes you are familiar with the ResourceSpace system, and would like to begin accessing data from ResourceSpace remotely.
The Remote API system allows you to make requests to your ResourceSpace installation via simple URLS for GET requests or POSTs (for file upload, for example) via curl.
Installation
You must have the php curl and json extensions and it is recommended that you have the mcrypt extension for more advanced encryption.
Install ResourceSpace via an SVN checkout.
The current code includes plugin files that allow the api system to work. To enable, in config.php, set:
$enable_remote_apis=true;
$api_scramble_key="test1234"; // change this if you haven't gone through the setup.php process.
Then activate the api_core plugin and any apis that are necessary for you via Team Center-> Manage Plugins. The current examples are api_search, api_alt_file, and api_upload.
Navigate to plugins/api_core/index.php in your browser
You should see your authentication key, which is specific to your current user and when using it the results will inherit all language entries, permissions, and configurations on that account. You will also see a hash key which is to be used for signing requests on the client side by creating an skey parameter. Following that is a list of APIs available to the user, readme files to explain the API, and a base call.
We highly recommend that if you're using remote APIs, you should also secure your installation with SSL
Architecture
ResourceSpace Remote APIs are plugins. This means that each API method is independent of all others. This allows private, customized APIs to be easily created, and further core APIs to be easily created based on others. You use the Plugin Manager to restrict access to APIs for particular User Groups. You only need to activate the APIs that are relevant to your installation.
The authentication key is composed of basic information (username and password hash) encrypted with a secret password on the server. This allows the authentication key to be used for authentication without revealing in clear text the username and password to the server. Having an authentication key means that you have access to the ResourceSpace account, but the authentication key itself won't give you access to anything other than permitted APIs. The authentication key should be kept secret just like a username and password combination, but it is much less dangerous to lose the authentication key, since it allows limited access to certain services. APIs that need more security can optionally implement more secure procedures, such as requiring that the request be signed with a hash created with a user-specific shared key. This is generally enabled by setting a config in the plugin, and may eventually be administrable through a web interface. This user-specific hash to sign requests is available in plugins/api_core/index.php
Plugin Structure
API plugins follow a simple format:
Each API plugin must be prefixed with "api_".
Each plugin must include a config folder with a config.php file including the variable $plugin name['signed']=[false or true] in order to set the default for whether the plugin requires signed requests or not.
Each plugin requires a .yaml file to make it work with the Plugin Manager.
Each plugin requires a readme.txt file that explains usage information.
Finally, each plugin requires an index.php file which includes basic ResourceSpace functions, sets $api=true, authenticates the user via the Authentication Key, verifies that the plugin is available to the user, , optionally checks for signed requests, and finally gets any GET or POST variables in order produce and format the output. It is recommended that all plugins support json and xml output options via a content paramenter (ex. content=xml).
Creating Additional Plugins
You can easily create additional plugins by using existing plugins as templates.
The basic idea is that a plugin should expose a specific functionality, often a core ResourceSpace function (an internal API). They should allow variables to be passed to a ResourceSpace function and express some useful output.
Example plugins would be:
api_embed (get an embed code)
api_resource_types_fields (get resource types and field data)
api_resource (get resource data or original file path)
api_collection (get collection data or resources in a collection)
api_user (get users or edit users)
api_resource_edit (edit a field or resource property)
api_resource_request (find or edit resource requests)
api_statistics (get stats)
api_reports (get a report)
api_annotations (get annotation markup locations)
api_login (get auth key to login as a specific user via an admins permission level)
... etc. There are any number of custom apis that could be useful for particular applications. These will be developed as needed. I'd like to hear feedback from other developers about what APIs might be useful in the future.
Usage
API usage can generally be understood through using the API Accessibility page at plugins/api_core/index.php
This will show both the readme files for particular plugins and a base call to get you started.
To Do
Standardize response format when errors need to be handled; include status messages and error information.
