README.md

   1 runsOnPserverrunsOnPserver# CRUD Microservice (Gizmo)
   2
   3 ## Overview
   4 The CRUD microservice implements a set of RESTful APIs which allow a client to perform CREATE, UPDATE, GET, and DELETE operations on verticies and edges within the A&AI graph database.
   5
   6 ## Getting Started
   7
   8 ### Building The Microservice
   9
  10 After cloning the project, execute the following Maven command from the project's top level directory to build the project:
  11
  12     > mvn clean install
  13
  14 Now, you can build your Docker image:
  15
  16     > docker build -t openecomp/crud-service target
  17
  18 ### Deploying The Microservice
  19
  20 Push the Docker image that you have built to your Docker repository and pull it down to the location from which you will be running the service.
  21
  22 **Create the following directories on the host machine:**
  23
  24     ../logs
  25     ../appconfig
  26         ../appconfig/auth
  27
  28 You will be mounting these as data volumes when you start the Docker container.
  29
  30 #### Configuring the Microservice
  31
  32 Create configuration file **../appconfig/crud-api.properties**
  33
  34         # List of hostnames/addresses of the graph database
  35         crud.graph.host=graphhost1.onap.com,graphhost2.onap.com
  36
  37         # Port on which to connect to the graph database
  38         crud.graph.port=2181
  39
  40         # Name of the graph on which this service will operate
  41         crud.graph.name=aaigraphautomation
  42
  43         # Backend storage type for the graph.  Types currently supported:
  44         #  - cassandra
  45         #  - hbase
  46         crud.storage.backend.db=cassandra
  47
  48         # List of hostnames/addresses of the DMaaP/Kafka cluster on which to post notification events
  49         event.stream.hosts=kafkahost1.onap.com,kafkahost2.onap.com
  50
  51         # Number of events to bath up before posting to DMaaP/Kafka
  52         event.stream.batch-size=100
  53
  54         # Amount of time (in ms) to wait before sending batch of events (when batch does not reach batch-size)
  55         event.stream.batch-timeout=60000
  56
  57 Create configuration file **../appconfig/auth/crud-policy.json**
  58
  59 This policy file defines which client certificates are authorized to use the service's APIs.  An example policy file follows:
  60
  61     {
  62         "roles": [
  63             {
  64                 "name": "admin",
  65                 "functions": [
  66                     {
  67                         "name": "search", "methods": [ { "name": "GET" },{ "name": "DELETE" }, { "name": "PUT" }, { "name": "POST" } ]
  68                     }
  69                 ],
  70                 "users": [
  71                     {
  72                         "username": "CN=admin, OU=My Organization Unit, O=, L=Sometown, ST=SomeProvince, C=CA"
  73                     }
  74                 ]
  75             }
  76         ]
  77     }
  78
  79 Create keystore file **../appconfig/auth/tomcat\_keystore**
  80 _tomcat\_keystore_
  81
  82 Create a keystore with this name containing whatever CA certificates that you want your instance of the CRUD service to accept for HTTPS traffic.
  83
  84 #### Start the service
  85
  86 You can now start the Docker container in the following manner:
  87
  88         docker run -d \
  89             -p 9520:9520 \
  90                 -e CONFIG_HOME=/opt/app/crud-service/config/ \
  91                 -e KEY_STORE_PASSWORD={{obfuscated password}} \
  92                 -e KEY_MANAGER_PASSWORD=OBF:{{obfuscated password}} \
  93             -v /<path>/logs:/opt/aai/logroot/AAI-CRUD \
  94             -v /<path>/appconfig:/opt/app/crud-service/config \
  95             --name crud-service \
  96             {{your docker repo}}/crud-service
  97
  98 Where,
  99
 100     {{your docker repo}} = The Docker repository you have published your CRUD Service image to.
 101     {{obfuscated password}} = The password for your key store/key manager after running it through the Jetty obfuscation tool.
 102
 103 ## API Definitions
 104
 105 ### Echo API
 106
 107         URL: https://<host>:9520/services/crud-api/v1/echo-service/echo/<input>
 108         Method: GET
 109         Success Response: 200
 110
 111 ### Create Vertex
 112
 113 Vertex payload data is validated against oxm.
 114 * Mandatory attributes are required in payload
 115 * Data type validation is enforced
 116 * Defaults from oxm schema used when not specified in payload
 117
 118         URL: https://<host>:9520/services/inventory/v8/pserver/
 119         Method: POST
 120         Body:
 121                 {
 122                         "properties":{
 123                                 "ptnii-equip-name":"e-name",
 124                                 "equip-type":"server",
 125                                 "hostname":"myhost",
 126                                 "equip-vendor":"HP",
 127                                 "equip-model":"DL380p-nd",
 128                                 "fqdn":myhost.onap.net",
 129                                 "purpose":"my-purpose",
 130                                 "resource-version":"1477013499",
 131                                 "ipv4-oam-address":"1.2.3.4"
 132                         }
 133                 }
 134         Success Response:
 135                 Code: 201
 136                 Content:
 137                         {
 138                                 "id":"1130672",
 139                                 "type":"pserver",
 140                                 "url":"services/inventory/v8/pserver/1130672",
 141                                 "properties":{
 142                                         "ptnii-equip-name":"e-name",
 143                                         "equip-type":"server",
 144                                         "hostname":"myhost",
 145                                         "equip-vendor":"HP",
 146                                         "equip-model":"DL380p-nd",
 147                                         "fqdn":myhost.onap.net",
 148                                         "purpose":"my-purpose",
 149                                         "resource-version":"1477013499",
 150                                         "ipv4-oam-address":"1.2.3.4"
 151                                 }
 152                         }
 153         Error Response:
 154                 Code: 400 (BAD REQUEST)
 155                 Content: Error message describing the bad request failure.
 156                 Situation: Invalid Payload or schema error.
 157
 158                 Code: 403 (FORBIDDEN)
 159                 Content: Error message describing the Authorization failure.
 160                 Situation: Authorization failure.
 161
 162                 Code: 415 (UNSUPPORTED MEDIA TYPE)
 163                 Situation: Unsupported content type .
 164
 165                 Code: 500 (Internal Server Error)
 166                 Content: Error message describing the failure.
 167                 Situation: Any scenario not covered by the above error codes.
 168
 169 Optionally, a vertex can be created by posting to an endpoint which doesn't include the vertex type.
 170
 171         URL: https://<host>:9520/services/inventory/v8/
 172         Method: POST
 173         Body:
 174                 {
 175                         "type":"pserver",
 176                         "properties":{
 177                                 "ptnii-equip-name":"e-name",
 178                                 "equip-type":"server",
 179                                 "hostname":"myhost",
 180                                 "equip-vendor":"HP",
 181                                 "equip-model":"DL380p-nd",
 182                                 "fqdn":myhost.onap.net",
 183                                 "purpose":"my-purpose",
 184                                 "resource-version":"1477013499",
 185                                 "ipv4-oam-address":"1.2.3.4"
 186                         }
 187                 }
 188         Success Response:
 189                 Code: 201
 190                 Content:
 191                         {
 192                                 "id":"1130672",
 193                                 "type":"pserver",
 194                                 "url":"services/inventory/v8/pserver/1130672",
 195                                 "properties":{
 196                                         "ptnii-equip-name":"e-name",
 197                                         "equip-type":"server",
 198                                         "hostname":"myhost",
 199                                         "equip-vendor":"HP",
 200                                         "equip-model":"DL380p-nd",
 201                                         "fqdn":myhost.onap.net",
 202                                         "purpose":"my-purpose",
 203                                         "resource-version":"1477013499",
 204                                         "ipv4-oam-address":"1.2.3.4"
 205                                 }
 206                         }
 207         Error Response:
 208                 Code: 400 (BAD REQUEST)
 209                 Content: Error message describing the bad request failure.
 210                 Situation: Invalid Payload or schema error.
 211
 212                 Code: 403 (FORBIDDEN)
 213                 Content: Error message describing the Authorization failure.
 214                 Situation: Authorization failure.
 215
 216                 Code: 415 (UNSUPPORTED MEDIA TYPE)
 217                 Situation: Unsupported content type .
 218
 219                 Code: 500 (Internal Server Error)
 220                 Content: Error message describing the failure.
 221                 Situation: Any scenario not covered by the above error codes.
 222
 223 ### Get Vertex
 224
 225         URL: https://<host>:9520/services/inventory/v8/pserver/<id>
 226         Method: GET
 227         Success Response:
 228                 Code: 200
 229                 Content:
 230                         {
 231                                 "id":"1130672",
 232                                 "type":"pserver",
 233                                 "url":"services/inventory/v8/pserver/<id>",
 234                                 "properties":{
 235                                         "ptnii-equip-name":"e-name",
 236                                         "equip-type":"server",
 237                                         "hostname":"myhost",
 238                                         "equip-vendor":"HP",
 239                                         "equip-model":"DL380p-nd",
 240                                         "fqdn":myhost.onap.net",
 241                                         "purpose":"my-purpose",
 242                                         "resource-version":"1477013499",
 243                                         "ipv4-oam-address":"1.2.3.4"
 244                                 },
 245                                 "in":[
 246                                 ],
 247                                 "out":[
 248                                         {
 249                                                 "id":"1crwnu-6hc-d6vp-oe08g",
 250                                                 "type":"has",
 251                                                 "target":"services/inventory/v8/vserver/40964272",
 252                                                 "url":"services/inventory/relationships/v8/has/1crwnu-6hc-d6vp-oe08g"
 253                                         }
 254                                 ]
 255                         }
 256         Error Response:
 257                 Code: 404 (NOT FOUND)
 258                 Situation: Reource Not found
 259
 260                 Code: 403 (FORBIDDEN)
 261                 Content: Error message describing the Authorization failure.
 262                 Situation: Authorization failure.
 263
 264                 Code: 415 (UNSUPPORTED MEDIA TYPE)
 265                 Situation: Unsupported content type .
 266
 267                 Code: 500 (Internal Server Error)
 268                 Content: Error message describing the failure.
 269                 Situation: Any scenario not covered by the above error codes.
 270
 271 ### Get Vertices
 272
 273         URL: https://<host>:9520/services/inventory/v8/pserver/
 274         Optional Query Param: ?equip-vendor=HP
 275         Method: GET
 276         Success Response:
 277                 Code: 200
 278                 Content:
 279                         [
 280                                 {
 281                                         "id":"950296",
 282                                         "type":"pserver",
 283                                         "url":"services/inventory/v8/pserver/950296"
 284                                 },
 285                                 {
 286                                         "id":"1126576",
 287                                         "type":"pserver",
 288                                         "url":"services/inventory/v8/pserver/1126576"
 289                                 },
 290                                 {
 291                                         "id":"1032384",
 292                                         "type":"pserver",
 293                                         "url":"services/inventory/v8/pserver/1032384"
 294                                 }
 295                         ]
 296         Error Response:
 297                 Code: 404 (NOT FOUND)
 298                 Situation: Reource Not found
 299
 300                 Code: 403 (FORBIDDEN)
 301                 Content: Error message describing the Authorization failure.
 302                 Situation: Authorization failure.
 303
 304                 Code: 415 (UNSUPPORTED MEDIA TYPE)
 305                 Situation: Unsupported content type .
 306
 307                 Code: 500 (Internal Server Error)
 308                 Content: Error message describing the failure.
 309                 Situation: Any scenario not covered by the above error codes.
 310
 311 ### Update Vertex
 312
 313 The PUT command is used to modify an existing vertex.  By default, the vertex data is replaced by the content of the payload.  However, teh following parameter can be added to the header to perform a PATCH instead of a replace:
 314 **X-HTTP-Method-Override=Patch**
 315
 316         URL: https://<host>:9520/services/inventory/v8/pserver/<id>
 317         Method: PUT
 318         Body: Same as POST
 319         Success Response:
 320                 Code: 201
 321                 Content: Same as POST
 322         Error Response:
 323                 Code: 400 (BAD REQUEST)
 324                 Content: Error message describing the bad request failure.
 325                 Situation: Invalid Payload or schema error.
 326
 327                 Code: 403 (FORBIDDEN)
 328                 Content: Error message describing the Authorization failure.
 329                 Situation: Authorization failure.
 330
 331                 Code: 415 (UNSUPPORTED MEDIA TYPE)
 332                 Situation: Unsupported content type .
 333
 334                 Code: 500 (Internal Server Error)
 335                 Content: Error message describing the failure.
 336                 Situation: Any scenario not covered by the above error codes.
 337
 338 ### Patch Vertex
 339
 340         URL: https://<host>:9520/services/inventory/v8/pserver/<id>
 341         Method: PATCH (Content-Type header set to application/merge-patch+json)
 342         Body:
 343                 {
 344                         "properties":{
 345                                 "ptnii-equip-name":"e-name",
 346                                 "resource-version":"1477013499",
 347                                 "ipv4-oam-address":"1.2.3.99"
 348                         }
 349                 }
 350         Success Response:
 351                 Code: 200
 352                 Content: Same as POST
 353         Error Response:
 354                 Code: 400 (BAD REQUEST)
 355                 Content: Error message describing the bad request failure.
 356                 Situation: Invalid Payload or schema error.
 357
 358                 Code: 403 (FORBIDDEN)
 359                 Content: Error message describing the Authorization failure.
 360                 Situation: Authorization failure.
 361
 362                 Code: 415 (UNSUPPORTED MEDIA TYPE)
 363                 Situation: Unsupported content type .
 364
 365                 Code: 500 (Internal Server Error)
 366                 Content: Error message describing the failure.
 367                 Situation: Any scenario not covered by the above error codes.
 368
 369  ### Delete Vertex
 370
 371         URL: https://<host>:9520/services/inventory/v8/pserver/<id>
 372         Method: DELETE
 373         Success Response:
 374                 Code: 200
 375         Error Response:
 376                 Code: 404 (NOT FOUND)
 377                 Situation: Resource not found
 378
 379                 Code: 403 (FORBIDDEN)
 380                 Content: Error message describing the Authorization failure.
 381                 Situation: Authorization failure.
 382
 383                 Code: 415 (UNSUPPORTED MEDIA TYPE)
 384                 Situation: Unsupported content type .
 385
 386                 Code: 500 (Internal Server Error)
 387                 Content: Error message describing the failure.
 388                 Situation: Any scenario not covered by the above error codes.
 389
 390 ### Create Edge
 391
 392 When creating an edge, the CRUD service will validate:
 393 * properties match the defined schema
 394 * relationship is valid between the source and target
 395
 396         URL: https://<host>:9520/services/inventory/relationships/v8/runsOnPserver/
 397         Method: POST
 398         Body:
 399                 {
 400                         "source":"services/inventory/v8/vserver/0",
 401                         "target":"services/inventory/v8/pserver/7",
 402                         "properties":{
 403                                 "multiplicity":"many",
 404                                 "is-parent":true,
 405                                 "uses-resource":"true",
 406                                 "has-del-target":"true"
 407                         }
 408                 }
 409         Success Response:
 410                 Code: 201
 411                 Content:
 412                         {
 413                                 "id":"215x5m-6hc-d6vp-oe08g",
 414                                 "type":"runsOnPserver",
 415                                 "url":"services/inventory/relationships/v8/has/215x5m-6hc-d6vp-oe08g",
 416                                 "source":"services/inventory/v8/vserver/8400",
 417                                 "target":"services/inventory/v8/pserver/40964272",
 418                                 "properties":{
 419                                         "is-parent":"true",
 420                                         "multiplicity":"many",
 421                                         "has-del-target":"true",
 422                                         "uses-resource":"true"
 423                                 }
 424                         }
 425         Error Response:
 426                 Code: 400 (BAD REQUEST)
 427                 Content: Error message describing the bad request failure.
 428                 Situation: Invalid Payload or schema error.
 429
 430                 Code: 403 (FORBIDDEN)
 431                 Content: Error message describing the Authorization failure.
 432                 Situation: Authorization failure.
 433
 434                 Code: 415 (UNSUPPORTED MEDIA TYPE)
 435                 Situation: Unsupported content type .
 436
 437                 Code: 500 (Internal Server Error)
 438                 Content: Error message describing the failure.
 439                 Situation: Any scenario not covered by the above error codes.
 440
 441 Optionally, an edge can be created by posting to an endpoint which doesn't include the edge type.
 442
 443         URL: https://<host>:9520/services/inventory/relationships/v8/
 444         Method: POST
 445         Body:
 446                 {
 447                         "type":"runsOnPserver",
 448                         "source":"services/inventory/v8/vserver/0",
 449                         "target":"services/inventory/v8/pserver/7",
 450                         "properties":{
 451                                 "multiplicity":"many",
 452                                 "is-parent":true,
 453                                 "uses-resource":"true",
 454                                 "has-del-target":"true"
 455                         }
 456                 }
 457         Success Response:
 458                 Code: 201
 459                 Content: Same as above
 460         Error Response:
 461                 Code: 400 (BAD REQUEST)
 462                 Content: Error message describing the bad request failure.
 463                 Situation: Invalid Payload or schema error.
 464
 465                 Code: 403 (FORBIDDEN)
 466                 Content: Error message describing the Authorization failure.
 467                 Situation: Authorization failure.
 468
 469                 Code: 415 (UNSUPPORTED MEDIA TYPE)
 470                 Situation: Unsupported content type .
 471
 472                 Code: 500 (Internal Server Error)
 473                 Content: Error message describing the failure.
 474                 Situation: Any scenario not covered by the above error codes.
 475
 476 ### Get Edge
 477
 478         URL: https://<host>:9520/services/inventory/relationships/v8/runsOnPserver/<id>
 479         Method: GET
 480         Success Response:
 481                 Code: 200
 482                 Content:
 483                         {
 484                                 "id":"215x5m-6hc-d6vp-oe08g",
 485                                 "type":"runsOnPserver",
 486                                 "url":"services/inventory/relationships/v8/has/215x5m-6hc-d6vp-oe08g",
 487                                 "source":"services/inventory/v8/vserver/8400",
 488                                 "target":"services/inventory/v8/pserver/40964272",
 489                                 "properties":{
 490                                         "is-parent":"true",
 491                                         "multiplicity":"many",
 492                                         "has-del-target":"true",
 493                                         "uses-resource":"true"
 494                                 }
 495                         }
 496         Error Response:
 497                 Code: 404 (NOT FOUND)
 498                 Situation: Reource Not found
 499
 500                 Code: 403 (FORBIDDEN)
 501                 Content: Error message describing the Authorization failure.
 502                 Situation: Authorization failure.
 503
 504                 Code: 415 (UNSUPPORTED MEDIA TYPE)
 505                 Situation: Unsupported content type .
 506
 507                 Code: 500 (Internal Server Error)
 508                 Content: Error message describing the failure.
 509                 Situation: Any scenario not covered by the above error codes.
 510
 511 ### Get Edges
 512
 513         URL: https://<host>:9520/services/inventory/relationships/v8/runsOnPserver
 514         Optional Query Param: ?multiplicity=many
 515         Method: GET
 516         Success Response:
 517                 Code: 200
 518                 Content:
 519                         [
 520                                 {
 521                                         "id":"1crwnu-6hc-d6vp-oe08g",
 522                                         "type":"runsOnPserver",
 523                                         "url":"services/inventory/relationships/v8/runsOnPserver/1crwnu-6hc-d6vp-oe08g",
 524                                         "source":"services/inventory/v8/vserver/8400",
 525                                         "target":"services/inventory/v8/pserver/40964272"
 526                                 },
 527                                 {
 528                                         "id":"215x5m-6hc-d6vp-oe08g",
 529                                         "type":"runsOnPserver",
 530                                         "url":"services/inventory/relationships/v8/runsOnPserver/215x5m-6hc-d6vp-oe08g",
 531                                         "source":"services/inventory/v8/vserver/8400",
 532                                         "target":"services/inventory/v8/pserver/40964272"
 533                                 }
 534                         ]
 535         Error Response:
 536                 Code: 404 (NOT FOUND)
 537                 Situation: Reource Not found
 538
 539                 Code: 403 (FORBIDDEN)
 540                 Content: Error message describing the Authorization failure.
 541                 Situation: Authorization failure.
 542
 543                 Code: 415 (UNSUPPORTED MEDIA TYPE)
 544                 Situation: Unsupported content type .
 545
 546                 Code: 500 (Internal Server Error)
 547                 Content: Error message describing the failure.
 548                 Situation: Any scenario not covered by the above error codes.
 549
 550 ### Update Edge
 551
 552 The PUT command is used to modify an existing edge.  By default, the edge data is replaced by the content of the payload.  However, the following parameter can be added to the header to perform a PATCH instead of a replace:
 553 **X-HTTP-Method-Override=Patch**
 554
 555         URL: https://<host>:9520/services/inventory/relationships/v8/runsOnPserver/<id>
 556         Method: PUT
 557         Body: (**Note that the source and target can not be modified)
 558                 {
 559                         "properties":{
 560                                 "multiplicity":"many",
 561                                 "is-parent":true,
 562                                 "uses-resource":"true",
 563                                 "has-del-target":"true"
 564                         }
 565                 }
 566         Success Response:
 567                 Code: 200
 568                 Content: Same as POST
 569         Error Response:
 570                 Code: 400 (BAD REQUEST)
 571                 Content: Error message describing the bad request failure.
 572                 Situation: Invalid Payload or schema error.
 573
 574                 Code: 403 (FORBIDDEN)
 575                 Content: Error message describing the Authorization failure.
 576                 Situation: Authorization failure.
 577
 578                 Code: 415 (UNSUPPORTED MEDIA TYPE)
 579                 Situation: Unsupported content type .
 580
 581                 Code: 500 (Internal Server Error)
 582                 Content: Error message describing the failure.
 583                 Situation: Any scenario not covered by the above error codes.
 584
 585 ### Patch Edge
 586
 587         URL: https://<host>:9520/services/inventory/relationships/v8/runsOnPserver/<id>
 588         Method: PATCH (Content-Type header set to application/merge-patch+json)
 589         Body:
 590                 {
 591                         "properties":{
 592                                 "multiplicity":"many"
 593                         }
 594                 }
 595         Success Response:
 596                 Code: 200
 597                 Content: Same as POST
 598         Error Response:
 599                 Code: 400 (BAD REQUEST)
 600                 Content: Error message describing the bad request failure.
 601                 Situation: Invalid Payload or schema error.
 602
 603                 Code: 403 (FORBIDDEN)
 604                 Content: Error message describing the Authorization failure.
 605                 Situation: Authorization failure.
 606
 607                 Code: 415 (UNSUPPORTED MEDIA TYPE)
 608                 Situation: Unsupported content type .
 609
 610                 Code: 500 (Internal Server Error)
 611                 Content: Error message describing the failure.
 612                 Situation: Any scenario not covered by the above error codes.
 613
 614 ### Delete Edge
 615
 616         URL: https://<host>:9520/services/inventory/relationships/v8/runsOnPserver/<id>
 617         Method: DELETE
 618         Success Response:
 619                 Code: 200
 620         Error Response:
 621                 Code: 404 (NOT FOUND)
 622                 Situation: Resource not found
 623
 624                 Code: 403 (FORBIDDEN)
 625                 Content: Error message describing the Authorization failure.
 626                 Situation: Authorization failure.
 627
 628                 Code: 415 (UNSUPPORTED MEDIA TYPE)
 629                 Situation: Unsupported content type .
 630
 631                 Code: 500 (Internal Server Error)
 632                 Content: Error message describing the failure.
 633                 Situation: Any scenario not covered by the above error codes.
 634
 635
 636