Home

Welcome to the RESTful wiki!

RESTful v2.x is the current recommended version. The 1.x documentation has been retained for those still using that version, and to help those upgrading to 2.x to see what has changed.

Learning RESTful

• Tutorials & blog posts (2.x)
• Tutorials & blog posts (1.x)

The RESTful api: overview

• Consuming your API e.g. from a Javascript framework
• Documenting your API
• Using the API from within Drupal

Creating Endpoints

Defining your own RESTful resource plugin.

• Defining a resource plugin (1.x)
• Defining a resource plugin (2.x)
• Resource plugin definition properties (for 2.x)

Filtering, sorting and pagination

• filtering
• sorting
• pagination

Public fields

• defining the public fields (2.x) — also see 1.x
• Using process callbacks to modify field data
• specifying available HTTP methods for each field (was create_or_update_passthrough in 1.x)

Relationships:

• adding related resource data

Going deeper:

• defining the endpoint's available routes (URLs)

OPTIONS and Resource discovery

• about a resource's OPTIONS request

Data providers

RESTful 2.x comes with numerous "data provider" classes. The data provider class abstracts the data access functionality from the resource class.

• List of data providers available "out of the box".
• assigning a different data provider for your resource
• creating a custom data provider

Example custom data providers:

• access data from a secondary database
• creating a URL alias lookup with DataProviderDbQuery
• access published and unpublished nodes

Formatters

• about RESTful's response formatters

Authentication

• Authenticating with Drupal via REST

How to upgrade to RESTful 2.x

Read Upgrading from 1.x to 2.x.

Common scenarios & recipes

Commonly required

• supporting client-side auto-complete

Users

• requesting the current user information (also 1.x version)
• registering a new user
• filtering users by role

Entities

• saving an entity back to Drupal
• using Drupal core's block visibility to return entities visible at a specified path
• Filter on taxonomy term name, instead of term ID
• custom field access control

Client-side Frameworks

• usage with Backbone.js
• usage with EmberJS (3-part series)

Edge cases

• working with "old-school" modules that directly add data to an entity (e.g. in node_load)? Read what do to when a property isn't available.
• Using a different field for URL ID
• Creating a resource that takes data from a secondary database

Frequently asked questions

See the FAQ section.

When things go wrong

Check through this list to see if you've forgotten anything.