src/include/gnunet_jsonapi_lib.h

   1 /*
   2   This file is part of GNUnet
   3   Copyright (C) 2014, 2015, 2016 GNUnet e.V.
   4
   5   GNUnet is free software; you can redistribute it and/or modify it under the
   6   terms of the GNU General Public License as published by the Free Software
   7   Foundation; either version 3, or (at your option) any later version.
   8
   9   GNUnet is distributed in the hope that it will be useful, but WITHOUT ANY
  10   WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  11   A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  12
  13   You should have received a copy of the GNU General Public License along with
  14   GNUnet; see the file COPYING.  If not, If not, see <http://www.gnu.org/licenses/>
  15 */
  16 /**
  17  * @file gnunet_jsonapi_lib.h
  18  * @brief functions to parse jsonapi objects
  19  * @author Martin Schanzenbach
  20  */
  21 #ifndef GNUNET_JSONAPI_LIB_H
  22 #define GNUNET_JSONAPI_LIB_H
  23
  24 #include "gnunet_util_lib.h"
  25 #include "gnunet_rest_lib.h"
  26 #include "gnunet_json_lib.h"
  27
  28 #define GNUNET_JSONAPI_KEY_DATA "data"
  29
  30 #define GNUNET_JSONAPI_KEY_ID "id"
  31
  32 #define GNUNET_JSONAPI_KEY_TYPE "type"
  33
  34 #define GNUNET_JSONAPI_KEY_META "meta"
  35
  36 #define GNUNET_JSONAPI_KEY_ATTRIBUTES "attributes"
  37
  38 #define GNUNET_JSONAPI_KEY_CODE "code"
  39
  40 #define GNUNET_JSONAPI_KEY_TITLE "title"
  41
  42 #define GNUNET_JSONAPI_KEY_DETAIL "detail"
  43
  44 #define GNUNET_JSONAPI_KEY_SOURCE "source"
  45
  46 #define GNUNET_JSONAPI_KEY_LINKS "links"
  47
  48 #define GNUNET_JSONAPI_KEY_STATUS "status"
  49
  50 #define GNUNET_JSONAPI_KEY_ERRORS "errors"
  51
  52 /* ****************** JSONAPI parsing ******************* */
  53
  54 struct GNUNET_JSONAPI_Relationship;
  55
  56 struct GNUNET_JSONAPI_Error;
  57
  58 struct GNUNET_JSONAPI_Resource;
  59
  60 struct GNUNET_JSONAPI_Document;
  61
  62 /**
  63  * Specification for parsing a jsonapi relationship.
  64  *
  65  * @param jsonapi_obj where to store the jsonapi relationship
  66  */
  67 struct GNUNET_JSON_Specification
  68 GNUNET_JSON_spec_jsonapi_relationship (struct GNUNET_JSONAPI_Relationship **jsonapi_obj);
  69
  70 /**
  71  * Specification for parsing a jsonapi error.
  72  *
  73  * @param jsonapi_obj where to store the jsonapi error
  74  */
  75 struct GNUNET_JSON_Specification
  76 GNUNET_JSON_spec_jsonapi_error (struct GNUNET_JSONAPI_Error **jsonapi_obj);
  77
  78 /**
  79  * Specification for parsing a jsonapi resource.
  80  *
  81  * @param jsonapi_obj where to store the jsonapi resource
  82  */
  83 struct GNUNET_JSON_Specification
  84 GNUNET_JSON_spec_jsonapi_resource (struct GNUNET_JSONAPI_Resource **jsonapi_obj);
  85
  86 /**
  87  * Specification for parsing a jsonapi object.
  88  *
  89  * @param jsonapi_obj where to store the jsonapi object
  90  */
  91 struct GNUNET_JSON_Specification
  92 GNUNET_JSON_spec_jsonapi_document (struct GNUNET_JSONAPI_Document **jsonapi_obj);
  93
  94 /**
  95  * Delete a JSON API relationship
  96  *
  97  * @param res the JSON resource
  98  * @param result Pointer where the resource should be stored
  99  */
 100 void
 101 GNUNET_JSONAPI_relationship_delete (struct GNUNET_JSONAPI_Relationship *rel);
 102
 103
 104 /**
 105  * Add a JSON API error to document
 106  *
 107  * @param data The JSON API document to add to
 108  * @param res the JSON API error to add
 109  * @return the new number of resources
 110  */
 111 void
 112 GNUNET_JSONAPI_document_error_add (struct GNUNET_JSONAPI_Document *doc,
 113                                       struct GNUNET_JSONAPI_Error *err);
 114
 115 /**
 116  * String serialze jsonapi error to json
 117  *
 118  * @param data the JSON API error
 119  * @param result where to store the result
 120  * @return GNUNET_SYSERR on error else GNUNET_OK
 121  */
 122 int
 123 GNUNET_JSONAPI_error_to_json (const struct GNUNET_JSONAPI_Error *err,
 124                               json_t **result);
 125
 126 /**
 127  * Parse json to error object
 128  *
 129  * @param err_json JSON object
 130  * @param[out] err error object
 131  * @return GNUNET_OK on success
 132  */
 133 int
 134 GNUNET_JSONAPI_json_to_error (json_t *err_json,
 135                               struct GNUNET_JSONAPI_Error **err);
 136
 137 /**
 138  * Delete a JSON API error
 139  *
 140  * @param res the JSON error
 141  */
 142 void
 143 GNUNET_JSONAPI_error_delete (struct GNUNET_JSONAPI_Error *error);
 144
 145 /**
 146  * Create a JSON API resource
 147  *
 148  * @param type the JSON API resource type
 149  * @param id the JSON API resource id
 150  * @return a new JSON API resource or NULL on error.
 151  */
 152 struct GNUNET_JSONAPI_Resource*
 153 GNUNET_JSONAPI_resource_new (const char *type, const char *id);
 154
 155
 156 /**
 157  * String serialze jsonapi to json
 158  *
 159  * @param data the JSON API resource
 160  * @param result where to store the result
 161  * @return GNUNET_SYSERR on error else GNUNET_OK
 162  */
 163 int
 164 GNUNET_JSONAPI_resource_to_json (const struct GNUNET_JSONAPI_Resource *res,
 165                                  json_t **result);
 166
 167 /**
 168  * Parse json to resource object
 169  *
 170  * @param res_json JSON object
 171  * @param[out] res resource object
 172  * @return GNUNET_OK on success
 173  */
 174 int
 175 GNUNET_JSONAPI_json_to_resource (json_t *res_json,
 176                                  struct GNUNET_JSONAPI_Resource **res);
 177
 178 /**
 179  * Delete a JSON API resource
 180  *
 181  * @param res the JSON resource
 182  * @param result Pointer where the resource should be stored
 183  */
 184 void
 185 GNUNET_JSONAPI_resource_delete (struct GNUNET_JSONAPI_Resource *resource);
 186
 187 /**
 188  * Add a JSON API attribute
 189  *
 190  * @param res the JSON resource
 191  * @param key the key for the attribute
 192  * @param json the json_t attribute to add
 193  * @return #GNUNET_OK if added successfully
 194  *         #GNUNET_SYSERR if not
 195  */
 196 int
 197 GNUNET_JSONAPI_resource_add_attr (struct GNUNET_JSONAPI_Resource *resource,
 198                                   const char* key,
 199                                   json_t *json);
 200 /**
 201  * Read a JSON API attribute
 202  *
 203  * @param res the JSON resource
 204  * @param key the key for the attribute
 205  * @return the json attr
 206  */
 207 json_t*
 208 GNUNET_JSONAPI_resource_read_attr (const struct GNUNET_JSONAPI_Resource *resource,
 209                                    const char* key);
 210
 211
 212 /**
 213  * Check a JSON API resource id
 214  *
 215  * @param res the JSON resource
 216  * @param id the expected id
 217  * @return GNUNET_YES if id matches
 218  */
 219 int
 220 GNUNET_JSONAPI_resource_check_id (const struct GNUNET_JSONAPI_Resource *resource,
 221                                   const char* id);
 222
 223
 224 /**
 225  * Check a JSON API resource type
 226  *
 227  * @param res the JSON resource
 228  * @param type the expected type
 229  * @return GNUNET_YES if id matches
 230  */
 231 int
 232 GNUNET_JSONAPI_resource_check_type (const struct GNUNET_JSONAPI_Resource *resource,
 233                                     const char* type);
 234
 235
 236 /**
 237  * Create a JSON API primary data
 238  *
 239  * @param type the JSON API resource type
 240  * @param id the JSON API resource id
 241  * @return a new JSON API resource or NULL on error.
 242  */
 243 struct GNUNET_JSONAPI_Document*
 244 GNUNET_JSONAPI_document_new ();
 245
 246
 247 /**
 248  * Create a JSON API primary data from a string
 249  *
 250  * @param data the string of the JSON API data
 251  * @param Pointer where to store new jsonapi Object.
 252  * @return GNUNET_OK on success
 253  */
 254 int
 255 GNUNET_JSONAPI_document_parse (const char* data,
 256                                struct GNUNET_JSONAPI_Document** obj);
 257
 258
 259 /**
 260  * Delete a JSON API primary data
 261  *
 262  * @param type the JSON API resource type
 263  * @param id the JSON API resource id
 264  * @return a new JSON API resource or NULL on error.
 265  */
 266 void
 267 GNUNET_JSONAPI_document_delete (struct GNUNET_JSONAPI_Document *resp);
 268
 269 /**
 270  * Add a JSON API resource to primary data
 271  *
 272  * @param data The JSON API data to add to
 273  * @param res the JSON API resource to add
 274  * @return the new number of resources
 275  */
 276 void
 277 GNUNET_JSONAPI_document_resource_add (struct GNUNET_JSONAPI_Document *resp,
 278                                       struct GNUNET_JSONAPI_Resource *res);
 279 /**
 280  * Get a JSON API object resource count
 281  *
 282  * @param resp the JSON API object
 283  * @return the number of resources
 284  */
 285 int
 286 GNUNET_JSONAPI_document_resource_count (struct GNUNET_JSONAPI_Document *resp);
 287
 288 /**
 289  * Get a JSON API object resource num
 290  *
 291  * @param resp the JSON API object
 292  * @param num the number of the resource
 293  * @return the resource
 294  */
 295 struct GNUNET_JSONAPI_Resource*
 296 GNUNET_JSONAPI_document_get_resource (struct GNUNET_JSONAPI_Document *resp, int num);
 297
 298
 299 /**
 300  * Add a JSON API resource to primary data
 301  *
 302  * @param resp The JSON API data to add to
 303  * @param res the JSON API resource to add
 304  * @return the new number of resources
 305  */
 306 void
 307 GNUNET_JSONAPI_document_resource_remove (struct GNUNET_JSONAPI_Document *resp,
 308                                          struct GNUNET_JSONAPI_Resource *res);
 309
 310 /**
 311  * String serialze jsonapi primary data
 312  *
 313  * @param data the JSON API primary data
 314  * @param result where to store the result
 315  * @return GNUNET_SYSERR on error else GNUNET_OK
 316  */
 317 int
 318 GNUNET_JSONAPI_document_serialize (const struct GNUNET_JSONAPI_Document *resp,
 319                                    char **result);
 320
 321 /**
 322  * Check a JSON API resource id
 323  *
 324  * @param res the JSON resource
 325  * @return the resource id
 326  */
 327 char*
 328 GNUNET_JSONAPI_resource_get_id (const struct GNUNET_JSONAPI_Resource *resource);
 329
 330
 331 /* end of gnunet_jsonapi_lib.h */
 332
 333 /**
 334  * Check rest request for validity
 335  *
 336  * @param req handle to the request
 337  * @return GNUNET_OK if valid
 338  */
 339 int
 340 GNUNET_JSONAPI_check_request_acceptable (struct GNUNET_REST_RequestHandle *req);
 341
 342 /**
 343  * Check rest request for validity
 344  *
 345  * @param req handle to the request
 346  * @return GNUNET_OK if valid
 347  */
 348 int
 349 GNUNET_JSONAPI_check_request_supported (struct GNUNET_REST_RequestHandle *req);
 350
 351
 352 /**
 353  * Handle jsonapi rest request. Checks request headers for jsonapi compliance
 354  *
 355  * @param req rest request handle
 356  * @param handler rest request handlers
 357  * @param cls closure
 358  * @return GNUNET_OK if successful
 359  */
 360 int
 361 GNUNET_JSONAPI_handle_request (struct GNUNET_REST_RequestHandle *req,
 362                                const struct GNUNET_REST_RequestHandler *handlers,
 363                                struct GNUNET_REST_RequestHandlerError *err,
 364                                void *cls);
 365
 366 #endif