REST End Points

[Ben Woodhead]

Hey Everybody,

I wanted a simple and consistent way to create endpoints for pushing
and pulling data from the drupal using jquery (or anything that can
parse json). Right now it doesn't do any kind of message passing but
ideally you could hide the json messages and only expose associative
arrays.

What do you think about something like this:

/**
* Register endpoints example
* @return type
*/
function islandora_services_register_endpoints()
{
// Define the end points
return array(
'islandora_services' => array (
'myendpoint' => array (
'title' => 'test callback',
'function' => 'myendpoint_handler',
'param_count' => 1,
'example' => 'myendpoint/2345',
'security' => array('view')
),
'myendpoint2' => array (
'title' => 'test callback2',
'function' => 'myendpoint_handler2',
'param_count' => 2,
'example' => 'myendpoint/2345/235',
'security' => array('view')
),
)
);
}

/**
* Example callback
* @param type $param
*/
function islandora_services_myendpoint_handler($param) {
$results = "islandora_services_myendpoint_handler(".$param.");";
return $results;
}

/**
* Example callback
* @param type $param
*/
function islandora_services_myendpoint_handler2($param, $param2) {
$results = "islandora_services_myendpoint_handler(".$param.",".$param2.");";
return $results;
}

[Adam Vessey]

Sorry, perhaps I'm missing something, but doesn't this just duplicate
the hook_menu callback, while still relying on it at some point to make
the paths visible... There is additional cool functionality which we
should make use of in the hook_menu (autoloading/instantiation of
objects before passing to the associated callbacks (page, access and
perhaps title?)), but I don't think duplicating and then requiring
maintenance of Drupal internals is a good idea.

-Adam

[Ben Woodhead]

Hey Adam,

Yeah, it uses the menu system to provide the callbacks with some
additional routing.

The main reasons are:
- It separates the menu hooks from the rest end points
- It keeps the endpoints organized in one area
- It can give you a list of all the registered end points to be displayed
- It routes messages for you including serializing the data
- It allows me to create tons of endpoints to be used both inside and
outside of drupal

You can have a look at it if you want.

https://github.com/bwoodhead/islandora_services

Ben

[Adam Vessey]

One big glaring thing, which seems kinda pointless:
https://github.com/bwoodhead/islandora_services/blob/master/islandora_services.module#L30

Which create a number of hooks dynamically and just use the parameters in the same order as they're passed...  Instead of doing this nested loop, you could just do:

function islandora_services_menu() {
  $items = array();
  $items['islandora_services/rest'] = array(
    'title' => $params['title'],
    'page callback' => 'islandora_services_handler',
    'access arguments' => $params['security'],
    'type' => MENU_CALLBACK
  );
  $items['islandora_services/list'] = array(
    'title' => 'Islandora Services List',
    'page callback' => 'islandora_services_list_page',
    'access arguments' => array('view'),
    'type' => MENU_NORMAL_ITEM
  );
  return $items;
}

The next couple of parameters would get passed to the handler function anyway.

You also lose the ability to specify actual access functions, which we'll likely want to do in the (near) future to be able to account for XACML, which of course is not handled by the native user_access function.  This could of course be added in as well to the register_endpoints return, but then it looks even more like hook_menu.

This isn't quite RESTful, as it's not really verbs on resources you're specifying.  REST is supposed to deal more with the actual HTTP verbs POST, GET, PUT and DELETE to perform the ususal CRUD functionality (respectively) on resources.


Anyway...  To address the actual reasons:

- It separates the menu hooks from the rest end points
- It keeps the endpoints organized in one area

These two could be handled simply by calling a function which returns an array of your 'endpoints' into your respective module's hook_menu implementation, instead of creating a hook which is called from within a hook.

- It can give you a list of all the registered end points to be displayed

Seems like a better case for a hook_help implementation, than anything?  I'm not really sure how useful this would be, as you could essentially have one service per module, and then just have the module's help page tell you what it does.  Create a new group in the modules page or sommat, and lump them all under there, so you can see which are enabled.  Dunno...

- It routes messages for you including serializing the data

I'm not quite sure what you mean by routing, and maybe it's just not implementated yet, but I'm not seeing any serialization done in the islandora_services_handler function...  In anycase, serialization to JSON is handled simply enough with drupal_json (I seem to recall some caveat there, but anyway...).  (HT|X)ML serialization seems like it would require a library in and of itself, as it's rather dependant on the data.

- It allows me to create tons of endpoints to be used both inside and
outside of drupal

No it doesn't, the Drupal menu system does.  This is just another step of indirection.


Sorry if I sound a little harsh by times there...  But I feel creating yet another interface to another slightly different and already existing interface is just going to lead to a great deal of confusion.

-Adam

[Ben Woodhead]

Thanks for the response. The link you mentioned is to assign security
to each endpoint. You are correct the routing hasn't been added yet.
Yeah, I ment to say end point instead of rest, sorry about that. You
can have as many end points as you like from each module. The *rest*
of your comments are all valid and I see where you are going. :)
Drupal's menu system works well but I tend to think of display pages
and end points as being sperate things. Also, I know echoing json to
the screen instead of returning it to drupal does block drupal
rendering but it seems very clumsy. Again thanks for the comments, I
will give them some more thought.

Ben