2 This file is part of GNUnet
3 Copyright (C) 2010-2015 GNUnet e.V.
5 GNUnet is free software; you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published
7 by the Free Software Foundation; either version 3, or (at your
8 option) any later version.
10 GNUnet is distributed in the hope that it will be useful, but
11 WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 General Public License for more details.
15 You should have received a copy of the GNU General Public License
16 along with GNUnet; see the file COPYING. If not, write to the
17 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
22 * @author Martin Schanzenbach
25 * API for helper library to parse/create REST
27 * @defgroup rest REST library
28 * Helper library to parse/create REST
31 #ifndef GNUNET_REST_LIB_H
32 #define GNUNET_REST_LIB_H
34 #include "gnunet_util_lib.h"
35 #include "microhttpd.h"
38 #define GNUNET_REST_JSONAPI_KEY_DATA "data"
40 #define GNUNET_REST_JSONAPI_KEY_ID "id"
42 #define GNUNET_REST_JSONAPI_KEY_TYPE "type"
44 #define GNUNET_REST_HANDLER_END {NULL, NULL, NULL}
46 struct RestConnectionDataHandle
48 struct GNUNET_CONTAINER_MultiHashMap *url_param_map;
56 struct GNUNET_REST_RestConnectionHandler
59 * Http method to handle
66 const char *namespace;
71 void (*proc) (struct RestConnectionDataHandle *handle,
79 * Iterator called on obtained result for a REST result.
82 * @param resp the response
83 * @param status status code (HTTP)
85 typedef void (*GNUNET_REST_ResultProcessor) (void *cls,
86 struct MHD_Response *resp,
91 * Resource structs for JSON API
93 struct JsonApiResource;
96 * Responses for JSON API
101 * Create a JSON API resource
103 * @param type the JSON API resource type
104 * @param id the JSON API resource id
105 * @return a new JSON API resource or NULL on error.
107 struct JsonApiResource*
108 GNUNET_REST_jsonapi_resource_new (const char *type, const char *id);
111 * Delete a JSON API resource
113 * @param res the JSON resource
114 * @param result Pointer where the resource should be stored
117 GNUNET_REST_jsonapi_resource_delete (struct JsonApiResource *resource);
120 * Add a JSON API attribute
122 * @param res the JSON resource
123 * @param key the key for the attribute
124 * @param json the json_t attribute to add
125 * @return #GNUNET_OK if added successfully
126 * #GNUNET_SYSERR if not
129 GNUNET_REST_jsonapi_resource_add_attr (const struct JsonApiResource *resource,
133 * Read a JSON API attribute
135 * @param res the JSON resource
136 * @param key the key for the attribute
137 * @return the json attr
140 GNUNET_REST_jsonapi_resource_read_attr (const struct JsonApiResource *resource,
145 * Check a JSON API resource id
147 * @param res the JSON resource
148 * @param id the expected id
149 * @return GNUNET_YES if id matches
152 GNUNET_REST_jsonapi_resource_check_id (const struct JsonApiResource *resource,
157 * Check a JSON API resource type
159 * @param res the JSON resource
160 * @param type the expected type
161 * @return GNUNET_YES if id matches
164 GNUNET_REST_jsonapi_resource_check_type (const struct JsonApiResource *resource,
169 * Create a JSON API primary data
171 * @param type the JSON API resource type
172 * @param id the JSON API resource id
173 * @return a new JSON API resource or NULL on error.
175 struct JsonApiObject*
176 GNUNET_REST_jsonapi_object_new ();
180 * Create a JSON API primary data from a string
182 * @param data the string of the JSON API data
183 * @return a new JSON API resource or NULL on error.
185 struct JsonApiObject*
186 GNUNET_REST_jsonapi_object_parse (const char* data);
190 * Delete a JSON API primary data
192 * @param type the JSON API resource type
193 * @param id the JSON API resource id
194 * @return a new JSON API resource or NULL on error.
197 GNUNET_REST_jsonapi_object_delete (struct JsonApiObject *resp);
200 * Add a JSON API resource to primary data
202 * @param data The JSON API data to add to
203 * @param res the JSON API resource to add
204 * @return the new number of resources
207 GNUNET_REST_jsonapi_object_resource_add (struct JsonApiObject *resp,
208 struct JsonApiResource *res);
210 * Get a JSON API object resource count
212 * @param resp the JSON API object
213 * @return the number of resources
216 GNUNET_REST_jsonapi_object_resource_count (struct JsonApiObject *resp);
219 * Get a JSON API object resource num
221 * @param resp the JSON API object
222 * @param num the number of the resource
223 * @return the resource
225 struct JsonApiResource*
226 GNUNET_REST_jsonapi_object_get_resource (struct JsonApiObject *resp, int num);
230 * Add a JSON API resource to primary data
232 * @param resp The JSON API data to add to
233 * @param res the JSON API resource to add
234 * @return the new number of resources
237 GNUNET_REST_jsonapi_data_resource_remove (struct JsonApiObject *resp,
238 struct JsonApiResource *res);
241 * String serialze jsonapi primary data
243 * @param data the JSON API primary data
244 * @param result where to store the result
245 * @return GNUNET_SYSERR on error else GNUNET_OK
248 GNUNET_REST_jsonapi_data_serialize (const struct JsonApiObject *resp,
252 * Check if namespace is in URL.
254 * @param url URL to check
255 * @param namespace namespace to check against
256 * @retun GNUNET_YES if namespace matches
259 GNUNET_REST_namespace_match (const char *url, const char *namespace);
262 * Create JSON API MHD response
264 * @param data JSON result
265 * @retun MHD response
268 GNUNET_REST_create_json_response (const char *data);
272 GNUNET_REST_handle_request (struct RestConnectionDataHandle *conn,
273 const struct GNUNET_REST_RestConnectionHandler *handlers,
279 /** @} */ /* end of group */