README.md

   1 # Common REST Client Library
   2
   3 This library provides a single client implementation to be used by micro services for communicating via its REST API.
   4
   5 ---
   6
   7 ## Usage
   8 In order to make the _REST Client_ library available to your microservice, include the following dependency in your service's pom.xml:
   9
  10     <!-- Common REST Client Library -->
  11     <dependency>
  12         <groupId>org.openecomp.aai</groupId>
  13         <artifactId>rest-client</artifactId>
  14         <version>1.1.0-SNAPSHOT</version>
  15     </dependency>
  16
  17 ## Code Examples
  18
  19 ### Creating and Configuring a Client Instance
  20 In order to start talking to a service, you need to create a client instance and configure it.  The _RestClient_ uses a fluent interface which allows it to be both instantiated and configured as in the following examples:
  21
  22 i)  A client using an SSL Client Certificate:
  23
  24     // Create an instance of the Rest Client and configure it.
  25     RestClient myClient = new RestClient()
  26         .authenticationMode(RestAuthenticationMode.SSL_CERT)
  27         .validateServerHostname(false)
  28         .validateServerCertChain(true)
  29         .clientCertFile("certificate_filename")
  30         .trustStroe("trust_store_filename")
  31         .connectTimeoutMs(1000)
  32         .readTimeoutMs(1000)
  33
  34 ii) A client using SSL Basic-Auth:
  35
  36     // Create an instance of the Rest Client and configure it.
  37     RestClient myClient = new RestClient()
  38         .authenticationMode(RestAuthenticationMode.SSL_BASIC)
  39         .basicAuthUsername("username")
  40         .basicAuthPassword("password")
  41         .connectTimeoutMs(1000)
  42         .readTimeoutMs(1000)
  43
  44 iii) A client using non-authentication HTTP:
  45
  46     // Create an instance of the Rest Client and configure it.
  47     RestClient myClient = new RestClient()
  48         .authenticationMode(RestAuthenticationMode.HTTP_NOAUTH)
  49         .connectTimeoutMs(1000)
  50         .readTimeoutMs(1000)
  51
  52 Note, that all of the above configuration parameters are optional and will be set to default values if they are not specified.
  53
  54 ### Querying The A&AI
  55 Once your service has a client instance, it can query the _Active & Available Inventory_ by specifying an HTTP endpoint, headers, and the expected response format:
  56
  57         MultivaluedMap<String, String> headers = new MultivaluedMapImpl();
  58         headers.put("Accept", Arrays.asList(new String[]{"application/json"}));
  59         headers.put("X-FromAppId", Arrays.asList(new String[]{"APP-ID"}));
  60         headers.put("X-TransactionId", Arrays.asList(new String[]{UUID.randomUUID().toString()}));
  61
  62     OperationResult result = myClient.queryActiveInventory("http://some/endpoint", headers, RestClient.RESPONSE_MIME_TYPE.JSON);
  63
  64     // You can also specify number of re-tries:
  65     int retries = 3
  66     OperationResult result = myClient.queryActiveInventory("http://some/endpoint", headers, RestClient.RESPONSE_MIME_TYPE.JSON, retries);
  67
  68
  69 The result of the query is returned as an _OperationResult_ object, which can be unpacked in the following manner:
  70
  71 The standard HTTP result code received back from the _A&AI_ is accessible as follows:
  72
  73     int resultCode = getResultCode()
  74
  75 The actual result payload is accessible in the following manner:
  76
  77     String resultPayload = result.getResult()
  78
  79 Finally, in the event of a failure, a failure cause message will be populated and can be accessed as follows:
  80
  81     String failureCause = result.getFailureCause()