1 runsOnPserverrunsOnPserver# CRUD Microservice (Gizmo)
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.
8 ### Building The Microservice
10 After cloning the project, execute the following Maven command from the project's top level directory to build the project:
14 Now, you can build your Docker image:
16 > docker build -t openecomp/crud-service target
18 ### Deploying The Microservice
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.
22 **Create the following directories on the host machine:**
28 You will be mounting these as data volumes when you start the Docker container.
30 #### Configuring the Microservice
32 Create configuration file **../appconfig/crud-api.properties**
34 # List of hostnames/addresses of the graph database
35 crud.graph.host=graphhost1.onap.com,graphhost2.onap.com
37 # Port on which to connect to the graph database
40 # Name of the graph on which this service will operate
41 crud.graph.name=aaigraphautomation
43 # Backend storage type for the graph. Types currently supported:
46 crud.storage.backend.db=cassandra
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
51 # Number of events to bath up before posting to DMaaP/Kafka
52 event.stream.batch-size=100
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
57 Create configuration file **../appconfig/auth/crud-policy.json**
59 This policy file defines which client certificates are authorized to use the service's APIs. An example policy file follows:
67 "name": "search", "methods": [ { "name": "GET" },{ "name": "DELETE" }, { "name": "PUT" }, { "name": "POST" } ]
72 "username": "CN=admin, OU=My Organization Unit, O=, L=Sometown, ST=SomeProvince, C=CA"
79 Create keystore file **../appconfig/auth/tomcat\_keystore**
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.
84 #### Start the service
86 You can now start the Docker container in the following manner:
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 \
96 {{your docker repo}}/crud-service
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.
107 URL: https://<host>:9520/services/crud-api/v1/echo-service/echo/<input>
109 Success Response: 200
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
118 URL: https://<host>:9520/services/inventory/v8/pserver/
123 "ptnii-equip-name":"e-name",
124 "equip-type":"server",
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"
140 "url":"services/inventory/v8/pserver/1130672",
142 "ptnii-equip-name":"e-name",
143 "equip-type":"server",
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"
154 Code: 400 (BAD REQUEST)
155 Content: Error message describing the bad request failure.
156 Situation: Invalid Payload or schema error.
158 Code: 403 (FORBIDDEN)
159 Content: Error message describing the Authorization failure.
160 Situation: Authorization failure.
162 Code: 415 (UNSUPPORTED MEDIA TYPE)
163 Situation: Unsupported content type .
165 Code: 500 (Internal Server Error)
166 Content: Error message describing the failure.
167 Situation: Any scenario not covered by the above error codes.
169 Optionally, a vertex can be created by posting to an endpoint which doesn't include the vertex type.
171 URL: https://<host>:9520/services/inventory/v8/
177 "ptnii-equip-name":"e-name",
178 "equip-type":"server",
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"
194 "url":"services/inventory/v8/pserver/1130672",
196 "ptnii-equip-name":"e-name",
197 "equip-type":"server",
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"
208 Code: 400 (BAD REQUEST)
209 Content: Error message describing the bad request failure.
210 Situation: Invalid Payload or schema error.
212 Code: 403 (FORBIDDEN)
213 Content: Error message describing the Authorization failure.
214 Situation: Authorization failure.
216 Code: 415 (UNSUPPORTED MEDIA TYPE)
217 Situation: Unsupported content type .
219 Code: 500 (Internal Server Error)
220 Content: Error message describing the failure.
221 Situation: Any scenario not covered by the above error codes.
225 URL: https://<host>:9520/services/inventory/v8/pserver/<id>
233 "url":"services/inventory/v8/pserver/<id>",
235 "ptnii-equip-name":"e-name",
236 "equip-type":"server",
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"
249 "id":"1crwnu-6hc-d6vp-oe08g",
251 "target":"services/inventory/v8/vserver/40964272",
252 "url":"services/inventory/relationships/v8/has/1crwnu-6hc-d6vp-oe08g"
257 Code: 404 (NOT FOUND)
258 Situation: Resource Not found
260 Code: 403 (FORBIDDEN)
261 Content: Error message describing the Authorization failure.
262 Situation: Authorization failure.
264 Code: 415 (UNSUPPORTED MEDIA TYPE)
265 Situation: Unsupported content type .
267 Code: 500 (Internal Server Error)
268 Content: Error message describing the failure.
269 Situation: Any scenario not covered by the above error codes.
273 URL: https://<host>:9520/services/inventory/v8/pserver/
274 Optional Query Param: ?equip-vendor=HP
283 "url":"services/inventory/v8/pserver/950296"
288 "url":"services/inventory/v8/pserver/1126576"
293 "url":"services/inventory/v8/pserver/1032384"
297 Code: 404 (NOT FOUND)
298 Situation: Resource Not found
300 Code: 403 (FORBIDDEN)
301 Content: Error message describing the Authorization failure.
302 Situation: Authorization failure.
304 Code: 415 (UNSUPPORTED MEDIA TYPE)
305 Situation: Unsupported content type .
307 Code: 500 (Internal Server Error)
308 Content: Error message describing the failure.
309 Situation: Any scenario not covered by the above error codes.
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**
316 URL: https://<host>:9520/services/inventory/v8/pserver/<id>
321 Content: Same as POST
323 Code: 400 (BAD REQUEST)
324 Content: Error message describing the bad request failure.
325 Situation: Invalid Payload or schema error.
327 Code: 403 (FORBIDDEN)
328 Content: Error message describing the Authorization failure.
329 Situation: Authorization failure.
331 Code: 415 (UNSUPPORTED MEDIA TYPE)
332 Situation: Unsupported content type .
334 Code: 500 (Internal Server Error)
335 Content: Error message describing the failure.
336 Situation: Any scenario not covered by the above error codes.
340 URL: https://<host>:9520/services/inventory/v8/pserver/<id>
341 Method: PATCH (Content-Type header set to application/merge-patch+json)
345 "ptnii-equip-name":"e-name",
346 "resource-version":"1477013499",
347 "ipv4-oam-address":"1.2.3.99"
352 Content: Same as POST
354 Code: 400 (BAD REQUEST)
355 Content: Error message describing the bad request failure.
356 Situation: Invalid Payload or schema error.
358 Code: 403 (FORBIDDEN)
359 Content: Error message describing the Authorization failure.
360 Situation: Authorization failure.
362 Code: 415 (UNSUPPORTED MEDIA TYPE)
363 Situation: Unsupported content type .
365 Code: 500 (Internal Server Error)
366 Content: Error message describing the failure.
367 Situation: Any scenario not covered by the above error codes.
371 URL: https://<host>:9520/services/inventory/v8/pserver/<id>
376 Code: 404 (NOT FOUND)
377 Situation: Resource not found
379 Code: 403 (FORBIDDEN)
380 Content: Error message describing the Authorization failure.
381 Situation: Authorization failure.
383 Code: 415 (UNSUPPORTED MEDIA TYPE)
384 Situation: Unsupported content type .
386 Code: 500 (Internal Server Error)
387 Content: Error message describing the failure.
388 Situation: Any scenario not covered by the above error codes.
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
396 URL: https://<host>:9520/services/inventory/relationships/v8/runsOnPserver/
400 "source":"services/inventory/v8/vserver/0",
401 "target":"services/inventory/v8/pserver/7",
403 "multiplicity":"many",
405 "uses-resource":"true",
406 "has-del-target":"true"
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/0",
417 "target":"services/inventory/v8/pserver/7",
420 "multiplicity":"many",
421 "has-del-target":"true",
422 "uses-resource":"true"
426 Code: 400 (BAD REQUEST)
427 Content: Error message describing the bad request failure.
428 Situation: Invalid Payload or schema error.
430 Code: 403 (FORBIDDEN)
431 Content: Error message describing the Authorization failure.
432 Situation: Authorization failure.
434 Code: 415 (UNSUPPORTED MEDIA TYPE)
435 Situation: Unsupported content type .
437 Code: 500 (Internal Server Error)
438 Content: Error message describing the failure.
439 Situation: Any scenario not covered by the above error codes.
441 Optionally, an edge can be created by posting to an endpoint which doesn't include the edge type.
443 URL: https://<host>:9520/services/inventory/relationships/v8/
447 "type":"runsOnPserver",
448 "source":"services/inventory/v8/vserver/0",
449 "target":"services/inventory/v8/pserver/7",
451 "multiplicity":"many",
453 "uses-resource":"true",
454 "has-del-target":"true"
459 Content: Same as above
461 Code: 400 (BAD REQUEST)
462 Content: Error message describing the bad request failure.
463 Situation: Invalid Payload or schema error.
465 Code: 403 (FORBIDDEN)
466 Content: Error message describing the Authorization failure.
467 Situation: Authorization failure.
469 Code: 415 (UNSUPPORTED MEDIA TYPE)
470 Situation: Unsupported content type .
472 Code: 500 (Internal Server Error)
473 Content: Error message describing the failure.
474 Situation: Any scenario not covered by the above error codes.
476 ### Create Edge With Auto-Population Of Edge Properties
477 An alternate endpoint exists for creating edges which follows all of the conventions of the above endpoints, with the addition that properties defined in the db edge rules produced by the A&AI will be automatically populated for the edge.
479 URL: https://<host>:9520/services/resources/relationships/runsOnPserver/
483 "source":"services/inventory/v8/vserver/0",
484 "target":"services/inventory/v8/pserver/7",
493 "id":"215x5m-6hc-d6vp-oe08g",
494 "type":"runsOnPserver",
495 "url":"services/inventory/relationships/v8/has/215x5m-6hc-d6vp-oe08g",
496 "source":"services/inventory/v8/vserver/0",
497 "target":"services/inventory/v8/pserver/7",
499 "contains-other-v": "NONE",
500 "delete-other-v": "NONE",
502 "prevent-delete": "IN"
506 Code: 400 (BAD REQUEST)
507 Content: Error message describing the bad request failure.
508 Situation: Invalid Payload or schema error.
510 Code: 403 (FORBIDDEN)
511 Content: Error message describing the Authorization failure.
512 Situation: Authorization failure.
514 Code: 415 (UNSUPPORTED MEDIA TYPE)
515 Situation: Unsupported content type .
517 Code: 500 (Internal Server Error)
518 Content: Error message describing the failure.
519 Situation: Any scenario not covered by the above error codes.
521 The same option to POST to an endpoint without specifying a type in the URL exists for this endpoint as well:
523 URL: https://<host>:9520/services/resources/relationships/
527 "type":"runsOnPserver",
528 "source":"services/inventory/v8/vserver/0",
529 "target":"services/inventory/v8/pserver/7",
531 "multiplicity":"many",
533 "uses-resource":"true",
534 "has-del-target":"true"
539 Content: Same as above
541 Code: 400 (BAD REQUEST)
542 Content: Error message describing the bad request failure.
543 Situation: Invalid Payload or schema error.
545 Code: 403 (FORBIDDEN)
546 Content: Error message describing the Authorization failure.
547 Situation: Authorization failure.
549 Code: 415 (UNSUPPORTED MEDIA TYPE)
550 Situation: Unsupported content type .
552 Code: 500 (Internal Server Error)
553 Content: Error message describing the failure.
554 Situation: Any scenario not covered by the above error codes.
558 URL: https://<host>:9520/services/inventory/relationships/v8/runsOnPserver/<id>
564 "id":"215x5m-6hc-d6vp-oe08g",
565 "type":"runsOnPserver",
566 "url":"services/inventory/relationships/v8/has/215x5m-6hc-d6vp-oe08g",
567 "source":"services/inventory/v8/vserver/8400",
568 "target":"services/inventory/v8/pserver/40964272",
571 "multiplicity":"many",
572 "has-del-target":"true",
573 "uses-resource":"true"
577 Code: 404 (NOT FOUND)
578 Situation: Resource Not found
580 Code: 403 (FORBIDDEN)
581 Content: Error message describing the Authorization failure.
582 Situation: Authorization failure.
584 Code: 415 (UNSUPPORTED MEDIA TYPE)
585 Situation: Unsupported content type .
587 Code: 500 (Internal Server Error)
588 Content: Error message describing the failure.
589 Situation: Any scenario not covered by the above error codes.
593 URL: https://<host>:9520/services/inventory/relationships/v8/runsOnPserver
594 Optional Query Param: ?multiplicity=many
601 "id":"1crwnu-6hc-d6vp-oe08g",
602 "type":"runsOnPserver",
603 "url":"services/inventory/relationships/v8/runsOnPserver/1crwnu-6hc-d6vp-oe08g",
604 "source":"services/inventory/v8/vserver/8400",
605 "target":"services/inventory/v8/pserver/40964272"
608 "id":"215x5m-6hc-d6vp-oe08g",
609 "type":"runsOnPserver",
610 "url":"services/inventory/relationships/v8/runsOnPserver/215x5m-6hc-d6vp-oe08g",
611 "source":"services/inventory/v8/vserver/8400",
612 "target":"services/inventory/v8/pserver/40964272"
616 Code: 404 (NOT FOUND)
617 Situation: Resource Not found
619 Code: 403 (FORBIDDEN)
620 Content: Error message describing the Authorization failure.
621 Situation: Authorization failure.
623 Code: 415 (UNSUPPORTED MEDIA TYPE)
624 Situation: Unsupported content type .
626 Code: 500 (Internal Server Error)
627 Content: Error message describing the failure.
628 Situation: Any scenario not covered by the above error codes.
632 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:
633 **X-HTTP-Method-Override=Patch**
635 URL: https://<host>:9520/services/inventory/relationships/v8/runsOnPserver/<id>
637 Body: (**Note that the source and target can not be modified)
640 "multiplicity":"many",
642 "uses-resource":"true",
643 "has-del-target":"true"
648 Content: Same as POST
650 Code: 400 (BAD REQUEST)
651 Content: Error message describing the bad request failure.
652 Situation: Invalid Payload or schema error.
654 Code: 403 (FORBIDDEN)
655 Content: Error message describing the Authorization failure.
656 Situation: Authorization failure.
658 Code: 415 (UNSUPPORTED MEDIA TYPE)
659 Situation: Unsupported content type .
661 Code: 500 (Internal Server Error)
662 Content: Error message describing the failure.
663 Situation: Any scenario not covered by the above error codes.
667 URL: https://<host>:9520/services/inventory/relationships/v8/runsOnPserver/<id>
668 Method: PATCH (Content-Type header set to application/merge-patch+json)
672 "multiplicity":"many"
677 Content: Same as POST
679 Code: 400 (BAD REQUEST)
680 Content: Error message describing the bad request failure.
681 Situation: Invalid Payload or schema error.
683 Code: 403 (FORBIDDEN)
684 Content: Error message describing the Authorization failure.
685 Situation: Authorization failure.
687 Code: 415 (UNSUPPORTED MEDIA TYPE)
688 Situation: Unsupported content type .
690 Code: 500 (Internal Server Error)
691 Content: Error message describing the failure.
692 Situation: Any scenario not covered by the above error codes.
696 URL: https://<host>:9520/services/inventory/relationships/v8/runsOnPserver/<id>
701 Code: 404 (NOT FOUND)
702 Situation: Resource not found
704 Code: 403 (FORBIDDEN)
705 Content: Error message describing the Authorization failure.
706 Situation: Authorization failure.
708 Code: 415 (UNSUPPORTED MEDIA TYPE)
709 Situation: Unsupported content type .
711 Code: 500 (Internal Server Error)
712 Content: Error message describing the failure.
713 Situation: Any scenario not covered by the above error codes.