github.com/jbking/gohan@v0.0.0-20151217002006-b41ccf1c2a96/docs/source/schema.rst (about) 1 ============== 2 Gohan Schema 3 ============== 4 5 Gohan server provides REST API based on gohan schema definitions. 6 You can write gohan schema using json or YAML format. We will use YAML format in this document because of human reability. 7 8 You can take a look example schema definitions in etc/examples/ 9 10 Here is an example defining network and subnet resource. 11 12 .. code-block:: yaml 13 14 schemas: 15 - id: network 16 namespace: neutron 17 plural: networks 18 prefix: /v2.0 19 metadata: 20 template_format: "template/network.yaml" 21 schema: 22 properties: 23 description: 24 default: "" 25 permission: 26 - create 27 - update 28 title: Description 29 type: string 30 unique: false 31 id: 32 format: uuid 33 permission: 34 - create 35 title: ID 36 type: string 37 unique: false 38 name: 39 permission: 40 - create 41 - update 42 title: Name 43 type: string 44 unique: false 45 providor_networks: 46 default: {} 47 permission: 48 - create 49 - update 50 properties: 51 segmentaion_type: 52 enum: 53 - vlan 54 - vxlan 55 - gre 56 type: string 57 segmentation_id: 58 minimum: 0 59 type: integer 60 title: Provider Networks 61 type: object 62 unique: false 63 route_targets: 64 default: [] 65 items: 66 type: string 67 permission: 68 - create 69 - update 70 title: RouteTargets 71 type: array 72 unique: false 73 tenant_id: 74 format: uuid 75 permission: 76 - create 77 title: Tenant 78 type: string 79 unique: false 80 propertiesOrder: 81 - id 82 - name 83 - description 84 - providor_networks 85 - route_targets 86 - tenant_id 87 type: object 88 singular: network 89 title: Network 90 - id: subnet 91 parent: network 92 plural: subnets 93 prefix: /v2.0/neutron 94 schema: 95 properties: 96 cidr: 97 permission: 98 - create 99 title: Cidr 100 type: string 101 unique: false 102 description: 103 default: "" 104 permission: 105 - create 106 - update 107 title: Description 108 type: string 109 unique: false 110 id: 111 format: uuid 112 permission: 113 - create 114 type: string 115 unique: false 116 name: 117 permission: 118 - create 119 - update 120 title: Name 121 type: string 122 unique: false 123 tenant_id: 124 format: uuid 125 permission: 126 - create 127 title: TenantID 128 type: string 129 unique: false 130 propertiesOrder: 131 - id 132 - name 133 - description 134 - cidr 135 - tenant_id 136 type: object 137 singular: subnet 138 title: subnet 139 140 141 Schemas 142 ----------------------- 143 144 145 We will have a list of schemas to define a setup resources. 146 Each schema will have following properties. 147 148 - id -- resource id (unique) 149 - singular -- singular form of the schema name 150 - plural -- plural form of schema name 151 - title -- use visible label of resource title 152 - description -- a description of the schema 153 - schema -- json schema 154 155 Schemas might also have any of the following optional properties. 156 157 - parent -- the id of the parent schema 158 - namespace -- resource namespace 159 - prefix -- resource path prefix 160 - metadata -- application specific schema metadata (object) 161 162 You need these information to define REST API. 163 Please see json schema specification http://json-schema.org/ 164 165 Note that each resource must have unique "id" attribute for identity for the 166 each resources. You should also define "tenant_id" attribute if you want to 167 use owner-based access control described in policy section later. In case 168 no tenant_id is specified and owner-based access control is not enabled, 169 tenant_id will be assigned based on the authentication token used. 170 171 "singular" and "plural" attributes are used for wrapping returned resources 172 in additional dictionary during show and list calls respectively. 173 "plural" is also used during access URL constructions. 174 175 Namespace is an optional parameter that can be used to group schemas. If 176 a namespace has been specified, full namespace prefix will be prepended to the 177 schema prefix- see :ref:`namespace section <section-namespace>` for details. 178 179 You can use following properties in json schema. 180 181 182 Metadata 183 ------------------------------- 184 185 - type (string) 186 187 you can specify schema type. For example, gohan-webui will use 188 this value to determine wheather we show this schema link in the side menu 189 190 - nosync (boolean) 191 192 if nosync is true, we don't sync this resource for sync backend. 193 194 - state_versioning (boolean) 195 196 whether to support :ref:`state versioning <subsection-state-update>`, defaults to false. 197 198 Properties 199 ------------------------------- 200 201 We need to define properties of resource using following parameters. 202 203 - title 204 205 User visible label of the property 206 207 - format 208 209 Additional validation hint for this property 210 you can use defined attribute on http://json-schema.org/latest/json-schema-validation.html#anchor107 211 212 - type 213 214 properties type. 215 you can select from (string, number, integer, boolean, array and object) 216 Note that schema itself should be object type. 217 This can also be a two element list in case, attribute can be specified as null, e.g. ["string", "null"] 218 219 - default 220 221 defualt value of the property 222 223 - enum 224 225 You can specify list of allowed values 226 227 - required 228 229 List of required attributes to specified during creation 230 231 232 Following properties are extended from json schema v4. 233 234 - permission 235 236 permission is a list of allow actions for this property. 237 valid values contrains "create", "update". 238 Gohan generates json schema for craete API and update API based on this value. 239 Note that we can use this property for only first level properties. 240 241 - unique boolean (unique key constraint) 242 243 - detail (array) 244 245 This paramter will be used in user side. Possible values are strings including read, create, delete, list, update. 246 247 248 type string 249 ------------------------------- 250 251 type string is for defining string. 252 You can use following parameters for string. 253 254 - minLength max length of string 255 - maxLength min length of string 256 - pattern regexp pattern for this string 257 - relation (gohan extened property) define resource relation 258 - relation_property (gohan extened property) relation resource will be joined in list api requiest for this property name 259 260 eg. 261 262 .. code-block:: yaml 263 264 name: 265 permission: 266 - create 267 - update 268 title: Name 269 type: string 270 unique: false 271 272 type boolean 273 ------------------------------- 274 275 type boolean for boolean value 276 277 eg. 278 279 .. code-block:: yaml 280 281 admin_state: 282 permission: 283 - create 284 - update 285 title: admin_state 286 type: boolean 287 unique: false 288 289 290 type integer or type number 291 ------------------------------- 292 293 type integer or type number for numetric properites. 294 You can use following parmeters to define valid range 295 296 - maximum (number) and exclusiveMaximum (boolean) 297 - minimum (number) and exclusiveMinimum (boolean) 298 299 eg. 300 301 .. code-block:: yaml 302 303 age: 304 permission: 305 - create 306 - update 307 title: age 308 type: number 309 unique: false 310 311 type array 312 ------------------------------- 313 314 type array is for defining list of elements 315 316 - items 317 318 Only allowed for array type 319 You can define element type on this property. 320 321 eg. 322 323 .. code-block:: yaml 324 325 route_targets: 326 default: [] 327 items: 328 type: string 329 permission: 330 - create 331 - update 332 title: RouteTargets 333 type: array 334 unique: false 335 336 337 type object 338 ------------------------------- 339 340 Object type is for defining object in the resources. 341 Note that resource itself should be an object. 342 following parameters supported in object type. 343 344 - properties 345 346 Only allowed for object type 347 You can define properties of this object 348 349 - propertiesOrder (extended paramter in gohan) 350 351 Only allowed for object type 352 JSON has no ordering on object key. This could be problematic if you want to 353 generate UI. so you can define ordering of properties using propertiesOrder 354 355 eg. 356 357 .. code-block:: yaml 358 359 providor_networks: 360 default: {} 361 permission: 362 - create 363 - update 364 properties: 365 segmentaion_type: 366 enum: 367 - vlan 368 - vxlan 369 - gre 370 type: string 371 segmentation_id: 372 minimum: 0 373 type: integer 374 required: 375 - segmentation_type 376 - segmentation_id 377 title: Provider Networks 378 type: object 379 unique: false 380 381 382 383 Parent - child relationship 384 ------------------------------- 385 386 Resources can be a in parent - child relationship. It means that the child resource has a foreign key to its parent. 387 388 389 Note that there is no need to create <parent>_id property in child schema, it is added automatically when the schema is loaded to gohan. 390 391 eg. 392 393 .. code-block:: yaml 394 395 schemas: 396 - description: Test Device 397 id: test_device 398 parent: "" 399 singular: test_device 400 plural: test_devices 401 prefix: /v1.0 402 schema: 403 properties: 404 name: 405 default: "" 406 permission: 407 - create 408 - update 409 title: Name 410 type: string 411 unique: false 412 id: 413 permission: 414 - create 415 title: ID 416 type: string 417 format: uuid 418 required: 419 - segmentation_type 420 - segmentation_id 421 type: object 422 title: Test Device 423 - description: Test Physical Port 424 id: test_port 425 parent: "test_device" 426 singular: test_port 427 plural: test_ports 428 prefix: /v1.0 429 schema: 430 properties: 431 name: 432 default: "" 433 permission: 434 - create 435 - update 436 title: Name 437 type: string 438 unique: false 439 id: 440 permission: 441 - create 442 title: ID 443 type: string 444 format: uuid 445 type: object 446 title: Test Physical Port 447 448 449 Custom actions schema 450 ------------------------------- 451 452 Resources can have custom actions, beside CRUD. In order to define them, add actions section and define jsonschema 453 of allowed input format 454 455 eg. 456 457 .. code-block:: yaml 458 459 schemas: 460 - description: Server 461 id: server 462 parent: "" 463 singular: server 464 plural: server 465 prefix: /v1.0 466 schema: 467 properties: 468 name: 469 default: "" 470 permission: 471 - create 472 - update 473 title: Name 474 type: string 475 unique: false 476 management_ip: 477 default: "" 478 format: ipv4 479 permission: 480 - create 481 - update 482 title: Management IP 483 type: string 484 unique: false 485 id: 486 permission: 487 - create 488 title: ID 489 type: string 490 format: uuid 491 actions: 492 reboot: 493 path: /:id/reboot 494 method: POST 495 input: 496 type: object 497 properties: 498 message: 499 type: string 500 delay: 501 type: string 502 output: null 503 504 Then, register extension to handle it, e.g. 505 506 .. code-block:: javascript 507 508 gohan_register_handler("pre_action_reboot_in_transaction", function(context){ 509 // retrieve necessary details regarding vm from db 510 }); 511 512 gohan_register_handler("action_reboot", function(context){ 513 // handle reboot in southbound 514 }); 515 516 In order to query above action, POST to /v1.0/servers/:id/action with 517 518 Available events 519 520 - pre_$action 521 - pre_$action_in_transaction 522 - $action 523 - post_$action_in_transaction 524 - post_$action 525 526 .. code-block:: json 527 528 { 529 "reboot": { 530 "message": "Maintenance", 531 "delay": "1h" 532 } 533 }