docs/open_cli_schema_version_1_0.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3 .. Copyright 2017 Huawei Technologies Co., Ltd.
   4
   5 .. _open_cli_schema_version_1_0:
   6
   7 Open Command Line Interface (CLI) Schema Version (OCS) 1.0
   8 ==========================================================
   9
  10 Open CLI Platform (OCLIP) provides model based framework to implement
  11 Linux Commands for any given software products, by using YAML template
  12 based on the schematics defined in this document. In version 1.0,
  13 following aspects of commands are modeled as YAML schematics:
  14
  15 * Basic Command information
  16
  17 * Command line arguments
  18
  19 * Command outputs
  20
  21 * Software product information
  22
  23 * REST API details
  24
  25 * Command usage
  26
  27 open_cli_schema_version
  28 -----------------------
  29 OCLIP considers any YAML file with first line having the following entry
  30 as proper template.
  31
  32     open_cli_schema_version: 1.0
  33
  34 Here, 1.0 version is first version of this schema. In future, this version
  35 number will get incremented based on addition of new schematics or update of
  36 existing schematics.
  37
  38 name
  39 ----
  40 *name* entry allows to set the command name and it is recommended to use the
  41 following format:
  42
  43     <entity>-<action>
  44
  45     entity - Resource or a feature, for which command is provided
  46
  47     action - Functionality performed on the entity
  48
  49     For example, to implement a command to *start* a given *service*.
  50     set the name as:
  51
  52     **name** : **service-start**
  53
  54 *CAUTION*: name should not have any space character in it.
  55
  56 description
  57 -----------
  58 *description* entry allows to write detailed usage of the command. It could be
  59 a line or a paragraph as given example here.
  60
  61 **a line**
  62
  63     description: Start the given service
  64
  65 **a paragraph**
  66
  67     description: |
  68         Start the given service. To see the available services in the system
  69         use the command *service-list*
  70
  71 info
  72 -------
  73 product
  74 ~~~~~~~~
  75 *product* entry allows to tag the command template with the software product
  76 name and version, for which command is implemented and is recommended to use
  77 the following format:
  78
  79     <product>-<version>
  80
  81     product - Short name of the product
  82
  83     action - Version of the product
  84
  85     For example, to implement a command for Open Network Automation Platform
  86     (onap) version amsterdam, set the version as:
  87
  88     **product** : **onap-amsterdam**
  89
  90 *CAUTION*: product should not have any space character in it.
  91
  92
  93 parameters
  94 ---------
  95 Every command has set of arguments to provide the input values and *parameters*
  96 section allows to add the required arguments details such as name, description,
  97 etc as list of entries.
  98
  99 name
 100 ~~~~
 101 *name* entry uniquely identifies the given argument. It can be of any
 102 alpha-numerical characters and dash(-). For example to provide the http port of
 103 an service, the parameter could be:
 104
 105     parameters:
 106       \- **name: service-port**
 107
 108 description
 109 ~~~~~~~~~~~
 110 *description* entry allows to provide the details of the parameter. Its
 111 supported in similar approach with command *description* defined in above
 112 section. For example service-port could be described as:
 113
 114     parameters:
 115       \- name: service-port
 116
 117       **description: Service HTTP port.**
 118
 119 is_optional
 120 ~~~~~~~~~~~
 121 *is_optional* entry allows to set the parameter is mandatory or not. By default,
 122 this entry is false. For example service-port could be made as as optional:
 123
 124     parameters:
 125       \- name: service-port
 126
 127       description: Service HTTP port.
 128
 129       **is_optional: true**
 130
 131 is_secured
 132 ~~~~~~~~~~~
 133 *is_secured* entry allows to set the parameter is secured or not. By default,
 134 this entry is false. This is very useful for password kind of parameters.
 135
 136 For example service-port could be made as in-secured:
 137
 138     parameters:
 139       \- name: service-port
 140
 141       description: Service HTTP port.
 142
 143       is_optional: true
 144
 145       **is_secured: false**
 146
 147 default_value
 148 ~~~~~~~~~~~~~
 149 *default_value* entry helps to provide the default value for the given parameter
 150 when that parameter is not provided during command execution.
 151
 152 Based on the *type* of parameter, default values are assigned as:
 153
 154 +---------------+------------------------------------------------------------+
 155 |       Type    |              Default value                                 |
 156 +===============+============================================================+
 157 | bool          | false                                                      |
 158 +---------------+------------------------------------------------------------+
 159 | uuid          | Auto-generated uuid-4 string                               |
 160 +---------------+------------------------------------------------------------+
 161 | string        | Blank. Also it can be set default values from the system   |
 162 |               | environment variable by mentioning it in the form of :     |
 163 |               |                                                            |
 164 |               | parameters:                                                |
 165 |               |     - default_value: ${ENV-VARIABLE-NAME}                  |
 166 +---------------+------------------------------------------------------------+
 167
 168 For example to provide the http port of an service, the parameter could be:
 169
 170     parameters:
 171       \- name: service-port
 172
 173       description: Service HTTP port.
 174
 175       is_optional: true
 176
 177       is_secured: false
 178
 179       **default_value: 8080**
 180
 181
 182 type
 183 ~~~~
 184 *type* entry allows to set the type of parameter such as boolean, integer, etc.
 185 For example to provide the http port of an service, the parameter type could be:
 186
 187     parameters:
 188       \- name: service-port
 189
 190       description: Service HTTP port.
 191
 192       is_optional: true
 193
 194       is_secured: false
 195
 196       default_value: 8080
 197
 198       **type: long**
 199
 200 Platform supports following types of parameter:
 201
 202 string
 203 ^^^^^^
 204 Any parameter value having a work or a line, string type is appropriate one. By
 205 default it is set to blank.
 206
 207 digit
 208 ^^^^^^
 209 Any parameter value having digit such as integers or floating values. For this
 210 type of parameter, platform does not set any default value. so while writing
 211 the parameter schematics, author should set the *default_value* if needed.
 212
 213 json
 214 ^^^^
 215 To set the value of parameter as JSON. Platform allows to input the JSON values
 216 either as direct one line string for simple json or complete file path for
 217 providing the complex json value. While user execute the command, based on the
 218 value of the JSON parameter, it could given as string or file path.
 219
 220 File path could start in the form of file://, http://, ftp://.
 221
 222 text
 223 ^^^^
 224 To set the value of parameter as text. Platform allows to input the text values
 225 either as direct one line string for simple text or complete file path for
 226 providing the complex text value. While user execute the command, based on the
 227 value of the text parameter, it could given as string or file path.
 228
 229 File path could start in the form of file://, http://, ftp://.
 230
 231 yaml
 232 ^^^^
 233 To set the value of parameter as yaml content. Platform allows to input the
 234 yaml values as complete file path. While user execute the command, YAML file
 235 needs to be created and provided that file's complete path as input value.
 236
 237 File path could start in the form of file://, http://, ftp://.
 238
 239 bool
 240 ^^^^
 241 This type allows to set the parameter value to either true or false. By
 242 default, its value is false, So, when user wants to input the boolean parameter
 243 its sufficient to mention the parameter option with out mentioning 'true'.
 244 For example, assume that command named 'login' defines the boolean input
 245 parameter 'is_secure_connection' to set the service connection is secured or
 246 not. For this command, while user input the value for parameter
 247 'is_secure_connection', it is sufficient to mention the parameter without
 248 passing value. Both of the following command will have same effect:
 249
 250     login --is_secure_connection
 251
 252     login --is_secure_connection true
 253
 254 uuid
 255 ^^^^
 256 *uuid* type allows to make the parameter value as UUID. By default platform auto
 257 generates uuid-4 formated string.
 258
 259 url
 260 ^^^
 261 *url* type allows to make the parameter value of URL/URI. Platform does not
 262 provide any default value for this type. so Author should provide the
 263 *default_value*, if needed during the template is created.
 264
 265 binary
 266 ^^^^^^
 267 *binary* type is very useful to pass the parameter as binary file and user
 268 should pass the complete path of the file.
 269
 270 array
 271 ^^^^^^
 272 To provide the same parameter multiple times array type helps. For example, when
 273 the command 'rm' is used, multiple file paths could be provided to remove all of
 274 them. In this kind of scenarios, array type supports and each parameter type
 275 is *string*
 276
 277 map
 278 ^^^^
 279 This is similar to *array* type and only differs the way the values are passed.
 280 In this type, values should be in the form of
 281 '<parameter-name>=<parameter-value>'
 282
 283
 284 Optional and Positional parameters
 285 ----------------------------------
 286 The input arguments for a given command usually provided with prefixing options
 287 names or directly giving the value. Earlier case is called optional arguments
 288 and later is called as positional arguments. OCLIP platform supports both the
 289 type.
 290
 291 For optional arguments, two type of options are supported:
 292
 293 *short option*: option name is usually single character and when user input
 294 the corresponding parameter, who will prefix with single dash(-).
 295
 296 *long option*: option name is usually more than one characters and when user
 297 input the corresponding parameter, who will prefix with double dash(-).
 298
 299 For example, the service port could be defined as :
 300
 301     parameters:
 302       \ - name: service-port
 303
 304       description: Service HTTP port.
 305
 306       is_optional: true
 307
 308       is_secured: false
 309
 310       default_value: 8080
 311
 312       type: long
 313
 314       **short_option: p**
 315
 316       **long_option:  service-port**
 317
 318 When user inputs the service port, it could either of following formats
 319
 320     --service-port 8080
 321
 322     -p 8080
 323
 324 For postional arguments, author should not define both *short_option* and
 325 *long_option* and when OCLIP process this template, it will consider as
 326 positional arguments. There could be more than one positional arguments could
 327 be defined for a command, and OCLIP treats the sequence of the positional
 328 parameters defined under *parameters* section is consider as it's position. For
 329 example, consider the below example:
 330
 331     parameters:
 332         \- name: param1
 333
 334         short_option: p1
 335
 336         long_option: param1
 337
 338         \- name: param2
 339
 340         \- name: param3
 341
 342         short_option: p3
 343
 344         long_option: param3
 345
 346         \- name: param4
 347
 348         \- name: param5
 349
 350         short_option: p5
 351
 352         long_option: param5
 353
 354 In this case, param2 and param4 are positional arguments as they are defined
 355 with out short and long options. so position of param2 is 1, for param4, it's 2.
 356 When user inputs the value as :
 357
 358     --param1 v1 -p3 v3 v2 -p5 v5 v4
 359
 360 OCLIP platform identifies the positions in sequence. so for param2, value v2
 361 will be assigned and for param4, value v4 will be assigned.
 362
 363 *NOTE*: User should only concern on the sequence of positional arguments while
 364 giving the values and no need to worry about the position at which value should
 365 be provided. so all of below sequence will yield the same result.
 366
 367     --param1 v1 -p3 v3 **v2** -p5 v5 **v4**
 368
 369     **v2** --param1 v1 **v4** -p5 v5 -p3 v3
 370
 371     --param1 v1 -p3 -p5 v5 v3 **v2** **v4**
 372
 373 default_parameters
 374 ------------------
 375 OCLIP platform provides following default parameters for every command and
 376 author is allowed to customize the inclusion or exclusion of these input
 377 parameters for a given command.
 378
 379 name: host-username
 380 ~~~~~~~~~~~~~~~~~~~
 381
 382     type: string
 383
 384     description: Host user name
 385
 386     short_option: u
 387
 388     long_option: host-username
 389
 390     default_value: ${OPEN_CLI_HOST_USERNAME}
 391
 392     is_optional: false
 393
 394 name: host-password
 395 ~~~~~~~~~~~~~~~~~~~
 396
 397     type: string
 398
 399     description: Host user password
 400
 401     short_option: p
 402
 403     long_option: host-password
 404
 405     default_value: ${OPEN_CLI_HOST_PASSWORD}
 406
 407     is_secured: true
 408
 409     is_optional: false
 410
 411 name: host-url
 412 ~~~~~~~~~~~~~~
 413     type: url
 414
 415     description: Host url
 416
 417     short_option: m
 418
 419     long_option: host-url
 420
 421     is_optional: false
 422
 423     default_value: ${OPEN_CLI_HOST_URL}
 424
 425 name: help
 426 ~~~~~~~~~~
 427     type: string
 428
 429     description: Command help message
 430
 431     short_option: h
 432
 433     long_option: help
 434
 435     default_value: false
 436
 437 name: version
 438 ~~~~~~~~~~~~~
 439     type: string
 440
 441     description: Command service version
 442
 443     short_option: v
 444
 445     long_option: version
 446
 447     default_value: false
 448
 449 name: debug
 450 ~~~~~~~~~~~
 451     type: bool
 452
 453     description: Enable debug output
 454
 455     short_option: d
 456
 457     long_option: debug
 458
 459     default_value: false
 460
 461 name: format
 462 ~~~~~~~~~~~~
 463     type: string
 464
 465     description: Output formats, supported formats such as table, csv, json,
 466     yaml
 467
 468     short_option: f
 469
 470     long_option: format
 471
 472     default_value: table
 473
 474 name: long
 475 ~~~~~~~~~~~
 476     type: bool
 477
 478     description: whether to print all attributes or only short attributes
 479
 480     short_option: s
 481
 482     long_option: long
 483
 484     default_value: false
 485
 486 name: no-title
 487 ~~~~~~~~~~~~~~
 488     type: bool
 489
 490     description: whether to print title or not
 491
 492     short_option: t
 493
 494     long_option: no-title
 495
 496     default_value: true
 497
 498 name: no-auth
 499 ~~~~~~~~~~~~~
 500     type: bool
 501
 502     description: whether to authenticate user or not
 503
 504     short_option: a
 505
 506     long_option: no-auth
 507
 508     default_value: false
 509
 510 *NOTE*: no-auth parameter is very helpful to by-pass the login and logout phase
 511 of each commands. Please refer *service* section to find more details on login
 512 and logout.
 513
 514 results
 515 -------
 516 Every command produces the output and *results* section helps to define the
 517 details of command outputs such as list of output attributes, the direction in
 518 which, result could be printed. More details are as follows.
 519
 520 direction
 521 ~~~~~~~~~
 522 *direction* entity allows to configure the direction in which the results to be
 523 printed. It can be:
 524
 525 * *portrait* : To print the results in two columns. First column is the name of
 526   the attribute and second column is the value of the attribute. It's more useful
 527   while command does operations like creation of resource, viewing of resources.
 528
 529 * *landscape* : To print the results row vise in landscape mode. It's more
 530   useful while command does operations like listing of resource.
 531
 532 attributes
 533 ~~~~~~~~~~
 534 name
 535 ^^^^
 536 *name* entry uniquely identifies the given attribute. It can be of any
 537 alpha-numerical characters and dash(-). For example to print the status of an
 538 service, the attribute could be:
 539
 540     attributes:
 541       \- **name: service-status**
 542
 543 description
 544 ^^^^^^^^^^^
 545 *description* entry allows to provide the details of the attribute. It's
 546 supported in similar approach with command *description* defined in above
 547 section. For example service-status could be described as:
 548
 549     attributes:
 550       \- name: service-status
 551
 552         **description: Service current status.**
 553
 554 type
 555 ^^^^
 556 *type* entry allows to set the type of attribute such as string, digit, etc.
 557 Similar to the parameter's type. currently it supports only string type.
 558
 559 For example, service-status could be:
 560
 561  attributes:
 562
 563  \- name: service-status
 564
 565  description: Service current status.
 566
 567  **type: string**
 568
 569 scope
 570 ^^^^^
 571 When a given command produces many results, most of the time no need to print
 572 all the attributes. SO OCLIP platform provides this *scope* entry to configure
 573 the attribute is printed by default or user should request to print it. So
 574 there are two scopes:
 575
 576 * *short* : attribute configured with this option will always printed by default
 577
 578 * *long* : attriuted configured with this option will get printed only when
 579   user inputs the default parameter *long*, defined in *default_parameters*
 580   section. So to print all attributes of a command, user will input parameter:
 581
 582     --long
 583
 584 A sample attribute for service-status could be:
 585
 586   attributes:
 587       \- name: service-status
 588
 589       description: Service current status.
 590
 591       type: string
 592
 593       **scope: short**
 594
 595 http
 596 ----
 597 OCLIP is enhanced to support REST API based products and *http* section is
 598 provided to capture all required details for performing http operation for the
 599 given command.
 600
 601 service
 602 -------
 603 Whether its information technology(IT) domain or communication technology(CT)
 604 domain, every software product is made of one or more service components. For
 605 example, onap has different components like aai, msb, etc and these components
 606 provides different kind of resources/features and functionalities.
 607
 608 *service* entry allows to mention the details of the given software product's
 609 service. This is an section and is having entries defined in below sections.
 610
 611 name
 612 ~~~~
 613 *name* entry allows to configure the service name. For example, to configure
 614 service component 'aai' in onap-amsterdam product,
 615
 616     service:
 617         name: aai
 618
 619 *CAUTION*: This entry is very signification to discover this service from the
 620 service catalog and name should be matching with the service name registered
 621 in the catalog.
 622
 623 version
 624 ~~~~~~~
 625 *version* entry allows to mention the particular version of service for which
 626 command is implemented. For example, the service 'aai' in the product
 627 'onap-amsterdam' having versions like v11.
 628
 629     service:
 630         version: v11
 631
 632 *CAUTION*: This entry is very signification to discover this service from the
 633 service catalog and version should be matching with the service version
 634 registered in the catalog.
 635
 636 mode
 637 ~~~~
 638 Some software product provides catalog service , where all service of that
 639 product could be discovered. While other product does not. OCLIP provides
 640 support for both kind of these products to implement commands and *mode*
 641 entry allows to configure this mode of operation.
 642
 643 CLIP supports in two different mode.
 644
 645 In *catalog* mode, OCLIP will discover the service details based on given
 646 *name* and *version* from the configured *host-url* parameter. For example,
 647 the product 'onap-amsterdam' provides the service 'msb' as the catalog service where
 648 all other services will get registered. so OCLIP can discover the given
 649 service such as 'aai' from the catalog service 'msb'. In this mode, *host-url*
 650 will be configured with the *msb* service url. In this case:
 651
 652     service:
 653         mode: catalog
 654
 655 *NOTE*: To see the details of *host-url*, refer the section default_parameters
 656
 657 In *direct* mode, OCLIP will not perform the discovery operation and consider
 658 the given *host-url* as the direct service url. In this case:
 659
 660     service:
 661         mode: direct
 662
 663 *NOTE*: To see the details of *host-url*, refer the section default_parameters
 664
 665 --------------------
 666
 667 auth
 668 ~~~~
 669 There are different kind of authentication and authorization approach exist and
 670 for OCLIP provides support for following approaches. Based on the approach
 671 configured in the template, OCLIP will login before executing the command and
 672 logout afterwards.
 673
 674 none
 675 ^^^^^
 676 In this approach, no login and logout will be performed. This is useful during
 677 the development cycle, as well as some services are available in public
 678 without authentication of user. In this approach, OCLIP ignores the given
 679 *host-username* and *host-password*. So the none auth is defined by:
 680
 681     service:
 682         auth: none
 683
 684 *NOTE*: To see the details of *host-username* and *host-password*, refer the
 685 section default_parameters
 686
 687
 688 basic
 689 ^^^^^
 690 This is HTTP basic authentication approach and given *host-username* and
 691 *host-password* values are used to find the hash and use it as Authentication
 692 value. So the none auth is defined by:
 693
 694     service:
 695         auth: basic
 696
 697 *NOTE*: To see the details of *host-username* and *host-password*, refer the
 698 section default_parameters
 699
 700 --------------------
 701 request
 702 ~~~~~~~
 703 *request* section captures all HTTP request information as:
 704
 705 uri
 706 ^^^
 707 *uri* entry allows to mention the REST API URI. Based on the *service mode*,
 708 this entry will vary. * when the mode is 'direct', it should be configured with
 709 out *host-url* portion in it. For example, if the REST API is
 710 '<host-url>/v1/service1/resource1, in which
 711
 712 * /v1/service1 - base path
 713 * /resource1 - service resource path.
 714
 715 then this entry will be:
 716
 717     request:
 718         uri: /v1/service1/resource1
 719
 720 when the mode is 'catalog', OCLIP will discover the  base path from the
 721 'catalog' service, so this entry need to be configured only with resource path
 722 as:
 723
 724     request:
 725         uri: /resource1
 726
 727 method
 728 ^^^^^^
 729 *method* entry allows to configure the HTTP methods GET, PUT, POST, DELETE,
 730 etc. For example, to get the resource1:
 731
 732     request:
 733         uri: /resource1
 734
 735         method: GET
 736
 737 body
 738 ^^^^
 739 *body* entry allows to mention the request body in json format, by default.
 740 And OCLIP adds 'application/json' header in the HTTP request. Otherwise, body
 741 could have complete path to binary file, in case request body is binary and
 742 *multipart_entity_name* should be configured with entity name provided by REST
 743 API.
 744
 745 headers
 746 ^^^^^^^
 747 *headers* entry allows to add REST API specific headers. By default OCLIP adds
 748 'application/json' as content-type and accept, also it will adds authentication
 749 headers such as 'Authentication' in case *auth* is of type 'basic'.
 750
 751 For example, to add the sample header :
 752
 753     request:
 754         uri: /resource1
 755
 756         method: GET
 757
 758         headers:
 759             header1: value1
 760
 761             header2: value2
 762
 763 queries
 764 ^^^^^^^
 765 *queries* entry allows to add REST API specific queries. For example, to add
 766 the sample queries :
 767
 768     request:
 769         uri: /resource1
 770
 771         method: GET
 772
 773         queries:
 774             q1: value1
 775
 776             q2: value2
 777
 778
 779 context
 780 ^^^^^^^
 781 *context* entry allows to customize the HTTP request and response processing.
 782
 783 Following are the supported customization parameters:
 784
 785 *remove_empty_node* : By default, OCLIP does not remove the empty json entries
 786   in request body. Otherwise set this entry to true as below.
 787
 788     request:
 789
 790         context:
 791             remove_empty_node: true
 792
 793 success_codes
 794 ~~~~~~~~~~~~~
 795 Every REST API has set of success codes and OCLIP will treat the HTTP request
 796 made based on the value configured in these http sections, only if
 797 *success_codes* contains the HTTP response status code.
 798
 799 result_map
 800 ~~~~~~~~~~
 801 This section allows to configure the require 'jpath' expression to retrieve the
 802 values from the HTTP response body.
 803
 804 *NOTE*: Currently only http response body is supported only with json type.
 805
 806 For example, if a http response '{"service_status": "green"} then to retrieve
 807 the service status and assign to result *attribute* service_status as :
 808
 809     result_map:
 810         service_status: $b{$.service_status}
 811
 812 Here, $b is detailed in section 'macros' of this document. and
 813 '$.service_status' is jpath expression.
 814
 815 sample_response
 816 ~~~~~~~~~~~~~~~
 817 This entry allows to keep the sample HTTP response as reference to understand
 818 the result_map jpath expressions. OCLIP does not use this entry and is optional.
 819
 820 macros
 821 -------
 822 OCLIP platform provides various marcos to fill *http* entries with the value
 823 of *parameters*, *headers* , etc Every macro is in the form of <macro name>
 824 followed by {<macro details>}Followings are the supported macros:
 825
 826 +----------------+------------------------------------------------------------+
 827 |       Macro    |               Definitions                                  |
 828 +================+============================================================+
 829 | ${param-name}  | To retrieve the value from parameter named 'param-name'    |
 830 +----------------+------------------------------------------------------------+
 831 | $h{header-name}| To retrieve the value from header named 'header-name'      |
 832 +----------------+------------------------------------------------------------+
 833 | $q{query-name} | To retrieve the value from query named 'query-name'        |
 834 +----------------+------------------------------------------------------------+
 835 | $b{jpath}      | To retrieve the value from response body using the 'jpath' |
 836 |                | expression.                                                |
 837 +----------------+------------------------------------------------------------+