-------------------------------------------------------------------------------- RESTful Web Services for Drupal (restws) -------------------------------------------------------------------------------- Maintainers: * Wolfgang Ziegler (fago), wolfgang.ziegler@epiqo.com * Klaus Purer (klausi), klaus.purer@epiqo.com Exposes Drupal resources (e.g. entities) as RESTful web services. The module makes use of the Entity API and the information about entity properties (provided via hook_entity_property_info()) to provide resource representations. It aims to be fully compliant to the REST principles. Installation ------------ * Copy the whole restws directory to your modules directory (e.g. DRUPAL_ROOT/sites/all/modules) and activate the RESTful Web Services module. * There is no user interface or such needed. Usage / Testing --------------- * To obtain the JSON representation of an entity use your browser to visit http://example.com/node/1.json or http://example.com/user/1.json or http://example.com//.json for an example. * In order to access entities via this interface, permissions must be granted for the desired operation (e.g. "access content" or "create content" for nodes). Additionally each resource is protected with a RESTWS permission that can be configured at "admin/people/permissions#module-restws". * Some example outputs are given in the example_exports folder. Design goals and concept ------------------------ * Create a module that simply exposes Drupal's data (e.g. entities) as web resources, thus creating a simple RESTful web service. It aims to be fully compliant to the REST principles. * The module is strictly resource-oriented. No support for message-oriented or RPC-style web services. * Plain and simple. No need for endpoint configuration, all resources are available on the same path pattern. Access via HTTP only. * When the module is enabled all entities should be available at the URL path //, e.g. /node/123, /user/1 or /profile/789. * Resources are represented and exchanged in different formats, e.g. JSON or XML. The format has to be specified in every request. * The module defines resource for all entity types supported by the entity API as well as a JSON format. Modules may provide further resources and formats via hooks. * The module supports full CRUD (Create, Read, Update, Delete) for resources: * Create: HTTP POST / (requires HTTP Content-Type header set to the MIME type of ) * Read: HTTP GET //. * Update: HTTP PUT //. or HTTP PUT // (requires HTTP Content-Type header set to the MIME type of the posted format) * Delete: HTTP DELETE // Note: if you use cookie-based authentication then you also need to set the HTTP X-CSRF-Token header on all writing requests (POST, PUT and DELETE). You can retrieve the token from /restws/session/token with a standard HTTP GET request. * The representation can be json, xml etc. * The usual Drupal permission system is respected, thus permissions are checked for the logged in user account of the received requests. * Authentication can be achieved via separate modules, maybe making use of the standard Drupal cookie and session handling. The module comes with an optional HTTP Basic Authentication module (restws_auth_basic) that performs a user login with the credentials provided via the usual HTTP headers. Querying -------- The module also supports querying for resources: Query: HTTP GET /.?=& = By default RestWS simply outputs all resources available for the given type: /user.json The example above will output a JSON object containing up to 100 users available in an sub object called list. The XML output will simply create tags with the given type in parent type, which also is called list. The hard limit of 100 resources per request ensures that the database and webserver won't overload. The hard limit is defined by the system variable restws_query_max_limit, which can be overridden if necessary. You can filter for certain resources by passing parameters in the URL. These parameters consist of properties of the resource and a value for that property. The value of a property is always the schema field of it. So if you want to filter for an author, the value of the filter has to be the uid. If you want to filter for nodes with a certain term, then you have to use the tid of that term. You can only specify one value, so filtering for more than one tag, is currently not supported. /node.json?type=article&field_tags=17&author=1 By default the first field column will be used for the query. If you want another column, you can specify it in square brackets. /node.json?body[format]=filtered_html If a certain property isn't valid an HTTP status code 412 will be returned containing an error message. Meta Controls ------------- Additionally to the filters RestWS also supports meta controls, which allow you to control your output. Currently only sort and direction are supported. This two meta controls allow you to sort your output by a specific property of your resource for a certain direction. By default the direction will be ascending but if want to sort your output descending you have to use the keyword DESC for the meta control direction. /taxonomy_term.json?sort=tid&direction=DESC You can limit the results with the meta control limit which is by default 100. To navigate through the generated pages, you have to use meta control page. /node.json?limit=10&page=3 The output always has a self, a first and a last element, which contain a link to the current, first and last page. If your current page isn't the last or the first one, RestWS will also generate prev and next links. For xml they can be found in the tags in the first hierarchy. Sometimes it might be helpful to retrieve only the references to resources of a query. You can tell RestWS to output them by setting the meta control full to 0, by default it will be 1 and output the whole resources. /node.json?full=0 If one of your resource properties collides with one of RestWS meta control keywords, you have prefix it with property_, when specifying it as filter. Debugging --------- You can enable a debug logging facility by setting a variable in settings.php (e.g. in DRUPAL_ROOT/sites/default/settings.php): $conf['restws_debug_log'] = DRUPAL_ROOT . '/restws_debug.log'; It will write the details of every web service request to the file you have specified, e.g. to DRUPAL_ROOT/restws_debug.log.