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: Reource 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: Reource 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/8400",
417 "target":"services/inventory/v8/pserver/40964272",
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.
478 URL: https://<host>:9520/services/inventory/relationships/v8/runsOnPserver/<id>
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",
491 "multiplicity":"many",
492 "has-del-target":"true",
493 "uses-resource":"true"
497 Code: 404 (NOT FOUND)
498 Situation: Reource Not found
500 Code: 403 (FORBIDDEN)
501 Content: Error message describing the Authorization failure.
502 Situation: Authorization failure.
504 Code: 415 (UNSUPPORTED MEDIA TYPE)
505 Situation: Unsupported content type .
507 Code: 500 (Internal Server Error)
508 Content: Error message describing the failure.
509 Situation: Any scenario not covered by the above error codes.
513 URL: https://<host>:9520/services/inventory/relationships/v8/runsOnPserver
514 Optional Query Param: ?multiplicity=many
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"
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"
536 Code: 404 (NOT FOUND)
537 Situation: Reource Not found
539 Code: 403 (FORBIDDEN)
540 Content: Error message describing the Authorization failure.
541 Situation: Authorization failure.
543 Code: 415 (UNSUPPORTED MEDIA TYPE)
544 Situation: Unsupported content type .
546 Code: 500 (Internal Server Error)
547 Content: Error message describing the failure.
548 Situation: Any scenario not covered by the above error codes.
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**
555 URL: https://<host>:9520/services/inventory/relationships/v8/runsOnPserver/<id>
557 Body: (**Note that the source and target can not be modified)
560 "multiplicity":"many",
562 "uses-resource":"true",
563 "has-del-target":"true"
568 Content: Same as POST
570 Code: 400 (BAD REQUEST)
571 Content: Error message describing the bad request failure.
572 Situation: Invalid Payload or schema error.
574 Code: 403 (FORBIDDEN)
575 Content: Error message describing the Authorization failure.
576 Situation: Authorization failure.
578 Code: 415 (UNSUPPORTED MEDIA TYPE)
579 Situation: Unsupported content type .
581 Code: 500 (Internal Server Error)
582 Content: Error message describing the failure.
583 Situation: Any scenario not covered by the above error codes.
587 URL: https://<host>:9520/services/inventory/relationships/v8/runsOnPserver/<id>
588 Method: PATCH (Content-Type header set to application/merge-patch+json)
592 "multiplicity":"many"
597 Content: Same as POST
599 Code: 400 (BAD REQUEST)
600 Content: Error message describing the bad request failure.
601 Situation: Invalid Payload or schema error.
603 Code: 403 (FORBIDDEN)
604 Content: Error message describing the Authorization failure.
605 Situation: Authorization failure.
607 Code: 415 (UNSUPPORTED MEDIA TYPE)
608 Situation: Unsupported content type .
610 Code: 500 (Internal Server Error)
611 Content: Error message describing the failure.
612 Situation: Any scenario not covered by the above error codes.
616 URL: https://<host>:9520/services/inventory/relationships/v8/runsOnPserver/<id>
621 Code: 404 (NOT FOUND)
622 Situation: Resource not found
624 Code: 403 (FORBIDDEN)
625 Content: Error message describing the Authorization failure.
626 Situation: Authorization failure.
628 Code: 415 (UNSUPPORTED MEDIA TYPE)
629 Situation: Unsupported content type .
631 Code: 500 (Internal Server Error)
632 Content: Error message describing the failure.
633 Situation: Any scenario not covered by the above error codes.