Check whether an entity type supports UUID module before using it.
[project/restws.git] / restws.api.php
1 <?php
2
3 /**
4 * @file
5 * This file contains no working PHP code; it exists to provide additional
6 * documentation for doxygen as well as to document hooks in the standard
7 * Drupal manner.
8 */
9
10
11 /**
12 * @defgroup restws RestWS module integrations.
13 *
14 * Module integrations with the restws module.
15 */
16
17 /**
18 * @defgroup restws_hooks RestWS' hooks
19 * @{
20 * Hooks that can be implemented by other modules in order to extend restws.
21 */
22
23 /**
24 * Define restws compatible resources.
25 *
26 * This hook is required in order to add new restws resources.
27 *
28 * @return array
29 * An array of information about the module's provided resources.
30 * The array contains a sub-array for each resource, with the resource name as
31 * the key. Resource names may only contain lowercase alpha-numeric characters
32 * and underscores and should be prefixed with the providing module name.
33 * Possible attributes for each sub-array are:
34 * - label: The label of the resource. Start capitalized.
35 * - class: The name of the controller class for the resource. The class has
36 * to implement the RestWSResourceControllerInterface. Required.
37 * - menu_path: A relative path were the resource callback should lie. By
38 * default the resource name will be used as menu path. Optional.
39 *
40 * @see MyModuleBookResourceController
41 */
42 function hook_restws_resource_info() {
43 return array(
44 'mymodule_book' => array(
45 'label' => t('Book'),
46 'class' => 'MyModuleBookResourceController',
47 'menu_path' => 'api/mybook',
48 ),
49 'mymodule_status' => array(
50 'label' => t('Status'),
51 'class' => 'MyModuleStatusResourceController',
52 ),
53 );
54 }
55
56 /**
57 * Alter available resource information.
58 *
59 * @param array $resource_info
60 * Resource information as defined in hook_restws_resource_info(). You can
61 * move the path of a resouce by setting menu_info. In this example you'll
62 * have to retrieve nodes from /mypath.json or /mypath/1.json.
63 *
64 * @see hook_restws_resource_info()
65 */
66 function hook_restws_resource_info_alter(&$resource_info) {
67 $resource_info['node']['class'] = 'MySpecialNodeResourceController';
68 $resource_info['node']['menu_path'] = 'mypath';
69 }
70
71 /**
72 * Define restws compatible formats.
73 *
74 * This hook is required in order to add new restws formats.
75 *
76 * @return array
77 * An array of information about the module's provided formats.
78 * The array contains a sub-array for each format, with the format name as
79 * the key. Format names may only contain lowercase alpha-numeric characters
80 * and underscores.
81 * Possible attributes for each sub-array are:
82 * - label: The label of the format. Start capitalized.
83 * - class: The name of the class for the format. The class has to implement
84 * the RestWSFormatInterface. Required.
85 * - mime type: The official internet media type (MIME type) of the format.
86 * Required.
87 */
88 function hook_restws_format_info() {
89 return array(
90 'json' => array(
91 'label' => t('JSON'),
92 'class' => 'RestWSFormatJSON',
93 'mime type' => 'application/json',
94 ),
95 'xml' => array(
96 'label' => t('XML'),
97 'class' => 'RestWSFormatXML',
98 'mime type' => 'application/xml',
99 ),
100 );
101 }
102
103 /**
104 * Alter available format information.
105 *
106 * @param array $format_info
107 * Format information as defined in hook_restws_format_info()
108 *
109 * @see hook_restws_format_info()
110 */
111 function hook_restws_format_info_alter(&$format_info) {
112 $format_info['json']['class'] = 'MyJsonFormatHandler';
113 }
114
115 /**
116 * Alter the incoming request array.
117 *
118 * @param array $request
119 * A request array that contains the following items:
120 * - op: operation string, one of create, read, update or delete.
121 * - format: object implementing RestWSFormatInterface.
122 * - resource: object implementing RestWSResourceControllerInterface.
123 * - id: resource identifier or NULL for the create operation.
124 * - payload: array containing data attached to this request, if any.
125 */
126 function hook_restws_request_alter(array &$request) {
127 if ($request['resource']->resource() == 'node') {
128 $request['format'] = restws_format('json');
129 }
130 }
131
132 /**
133 * Alter the outgoing response.
134 *
135 * @param mixed $response
136 * The response data being returned by the REST service (not yet serialized).
137 * @param string $function
138 * The function being called on the REST service.
139 * @param string $format
140 * The name of the format serializing the response.
141 * @param RestWSResourceControllerInterface $resourceController
142 * The resource controller.
143 */
144 function hook_restws_response_alter(&$response, $function, $formatName, $resourceController) {
145 if ($function == 'viewResource' && $formatName == 'json') {
146 $response['site_name'] = variable_get('site_name', '');
147 }
148 }
149
150 /**
151 * Alter the list of allowed meta controls.
152 *
153 * @param array $controls
154 * A list of allowed meta controlers
155 */
156 function hook_restws_meta_controls_alter(&$controls) {
157 $controls['deep-load-refs'] = 'deep-load-refs';
158 }
159
160 /**
161 * @}
162 */
163
164 /**
165 * Example controller class for the mymodule_book resource.
166 */
167 class MyModuleBookResourceController implements RestWSResourceControllerInterface {
168
169 /**
170 * @see hook_entity_property_info()
171 * @see RestWSResourceControllerInterface::propertyInfo()
172 */
173 public function propertyInfo() {
174 return array(
175 'properties' => array(
176 'title' => array(
177 'type' => 'text',
178 'label' => t('Book title'),
179 'setter callback' => 'entity_property_verbatim_set',
180 ),
181 'author' => array(
182 'type' => 'text',
183 'label' => t('Author'),
184 'setter callback' => 'entity_property_verbatim_set',
185 ),
186 'pages' => array(
187 'type' => 'integer',
188 'label' => t('Number of pages'),
189 'setter callback' => 'entity_property_verbatim_set',
190 ),
191 'price' => array(
192 'type' => 'decimal',
193 'label' => t('Price'),
194 'setter callback' => 'entity_property_verbatim_set',
195 ),
196 ),
197 );
198 }
199
200 /**
201 * @see RestWSResourceControllerInterface::wrapper()
202 */
203 public function wrapper($id) {
204 $book = mymodule_book_load($id);
205 $info = $this->propertyInfo();
206 return entity_metadata_wrapper('mymodule_book', $book, array('property info' => $info['properties']));
207 }
208
209 /**
210 * @see RestWSResourceControllerInterface::create()
211 */
212 public function create(array $values) {
213 try {
214 $book = mymodule_book_save($values);
215 return $book->id;
216 }
217 catch (Exception $e) {
218 throw new RestWSException('Creation error', 406);
219 }
220 }
221
222 /**
223 * @see RestWSResourceControllerInterface::read()
224 */
225 public function read($id) {
226 return mymodule_book_load($id);
227 }
228
229 /**
230 * @see RestWSResourceControllerInterface::update()
231 */
232 public function update($id, array $values) {
233 throw new RestWSException('Not implemented', 501);
234 }
235
236 /**
237 * @see RestWSResourceControllerInterface::delete()
238 */
239 public function delete($id) {
240 try {
241 mymodule_book_delete($id);
242 }
243 catch (Exception $e) {
244 throw new RestWSException('Book not found', 404);
245 }
246 }
247
248 /**
249 * @see RestWSResourceControllerInterface::access()
250 */
251 public function access($op, $id) {
252 return mymodule_book_access($op, $id);
253 }
254
255 /**
256 * @see RestWSResourceControllerInterface::resource()
257 */
258 public function resource() {
259 return 'mymodule_book';
260 }
261 }