Merge pull request #17 from amadeus4dev/doc_update_26oct2018

Update authentication documentation and examples

Author: anthonyroux

README.md

@@ -59,7 +59,7 @@ import com.amadeus.resources.Location;
 public class AmadeusExample {
   public static void main(String[] args) throws ResponseException {
     Amadeus amadeus = Amadeus
-            .builder("[client_id]", "[client_secret]")
+            .builder("REPLACE_BY_YOUR_API_KEY", "REPLACE_BY_YOUR_API_SECRET")
             .build();
 
     Location[] locations = amadeus.referenceData.locations.get(Params
@@ -78,7 +78,7 @@ The client can be initialized directly.
 ```java
 //Initialize using parameters
 Amadeus amadeus = Amadeus
-        .builder("[client_id]", "[client_secret]")
+        .builder("REPLACE_BY_YOUR_API_KEY", "REPLACE_BY_YOUR_API_SECRET")
         .build();
 ```
 
@@ -123,10 +123,10 @@ in-depth information about every SDK method, its arguments and return types.
 
 This library conveniently maps every API path to a similar path.
 
-For example, `GET /v2/reference-data/urls/checkin-links?airline=1X` would be:
+For example, `GET /v2/reference-data/urls/checkin-links?airline=BA` would be:
 
 ```java
-amadeus.referenceData.urls.checkinLinks.get(Params.with("airline", "1X"));
+amadeus.referenceData.urls.checkinLinks.get(Params.with("airline", "BA"));
 ```
 
 Similarly, to select a resource by ID, you can pass in the ID to the **singular** path.
@@ -142,7 +142,7 @@ Keep in mind, this returns a raw `Resource`
 
 ```java
 Resource resource = amadeus.get('/v2/reference-data/urls/checkin-links',
-  Params.with("airline", "1X"));
+  Params.with("airline", "BA"));
 
 resource.getResult();
 ```
@@ -181,13 +181,18 @@ If a page is not available, the method will return `null`.
 
 The SDK makes it easy to add your own logger.
 
-```java
-require 'logger'
+```java TO FIX
+import java.util.logging.Logger;
+
+// Assumes the current class is called MyLogger
+private final static Logger LOGGER = Logger.getLogger(MyLogger.class.getName());
 
-amadeus = Amadeus::Client.new(
-  client_id: '...',
-  client_secret: '...',
-  logger: Logger.new(STDOUT)
+...
+
+Amadeus amadeus = Amadeus
+        .builder("REPLACE_BY_YOUR_API_KEY", "REPLACE_BY_YOUR_API_KEY")
+        .setLogger(LOGGER)
+        .build();
 )
 ```
 
@@ -198,29 +203,27 @@ variable.
 
 ```java
 Amadeus amadeus = Amadeus
-        .builder("[client_id]", "[client_secret]")
+        .builder("REPLACE_BY_YOUR_API_KEY", "REPLACE_BY_YOUR_API_SECRET")
         .setLogLevel("debug") // or warn
         .build();
 ```
 
 ## List of supported endpoints
-
 ```java
-// Flight Cheapest Date Search
-FlightDate[] flightDates = amadeus.shopping.flightDates.get(Params
-  .with("origin", "LON")
-  .and("destination", "FRA")
-  .and("duration", 3));
-
 // Flight Inspiration Search
 FlightDestination[] flightDestinations = amadeus.shopping.flightDestinations.get(Params
-  .with("origin", "LON"));
+  .with("origin", "MAD"));
+
+// Flight Cheapest Date Search
+FlightDate[] flightDates = amadeus.shopping.flightDates.get(Params
+  .with("origin", "NYC")
+  .and("destination", "MAD");
 
 // Flight Low-fare Search
 FlightOffer[] flightOffers = amadeus.shopping.flightOffers.get(Params
-  .with("origin", "MAD")
-  .and("destination", "OPO")
-  .and("departureDate", "2018-11-01"));
+  .with("origin", "NYC")
+  .and("destination", "MAD")
+  .and("departureDate", "2019-08-01"));
 
 // Flight Check-in Links
 CheckinLink[] checkinLinks = amadeus.referenceData.urls.checkinLinks.get(Params
@@ -231,11 +234,10 @@ Airline[] airlines = amadeus.referenceData.airlines.get(Params
   .with("IATACode", "BA"));
 
 // Airport & City Search (autocomplete)
-// Find all the cities and airports starting by the keyword 'Lon'
+// Find all the cities and airports starting by the keyword 'LON'
 Location[] locations = amadeus.referenceData.locations.get(Params
-  .with("keyword", "lon")
+  .with("keyword", "LON")
   .and("subType", Locations.ANY));
-
 // Get a specific city or airport based on its id
 Location location = amadeus.referenceData
   .location("ALHR").get();
@@ -247,36 +249,34 @@ Location[] locations = amadeus.referenceData.locations.airports.get(Params
 
 // Flight Most Searched Destinations
 FareSearch[] fareSearches = amadeus.travel.analytics.fareSearches.get(Params
-  .with("origin", "SFO")
-  .and("sourceCountry", "US")
-  .and("period", "2017-08"));
-
-// Flight Most Traveled Destinations
-AirTraffic[] airTraffics = amadeus.travel.analytics.airTraffic.traveled.get(Params
-  .with("origin", "NCE")
+  .with("origin", "MAD")
+  .and("sourceCountry", "SP")
   .and("period", "2017-08"));
 
 // Flight Most Booked Destinations
 AirTraffic[] airTraffics = amadeus.travel.analytics.airTraffic.booked.get(Params
-  .with("origin", "NCE")
+  .with("origin", "MAD")
   .and("period", "2017-08"));
 
+// Flight Most Traveled Destinations
+AirTraffic[] airTraffics = amadeus.travel.analytics.airTraffic.traveled.get(Params
+  .with("origin", "MAD")
+  .and("period", "2017-01"));
+
 // Flight Busiest Traveling Period
 Period[] busiestPeriods = amadeus.travel.analytics.airTraffic.busiestPeriod.get(Params
   .with("cityCode", "MAD")
   .and("period", "2017")
   .and("direction", BusiestPeriod.ARRIVING));
 
 // Hotel Search API
-// Get list of hotels by cityCode
+// Get list of hotels by city code
 HotelOffer[] offers = amadeus.shopping.hotelOffers.get(Params
-  .with("cityCode", "PAR"));
-  
+  .with("cityCode", "MAD"));
 // Get list of offers for a specific hotel
 HotelOffer offer = amadeus.shopping
   .hotel("SMPARCOL")
   .hotelOffers.get();
-  
 // Confirm the availability of a specific offer for a specific hotel
 Offer offer = amadeus.shopping
   .hotel("SMPARCOL")

src/main/java/com/amadeus/Amadeus.java

@@ -4,16 +4,21 @@
 import lombok.NonNull;
 
 /**
- * <p>The Amadeus API client. To initialize, use the builder as follows:</p>
+ * <p>
+ * The Amadeus API client. To initialize, use the builder as follows:
+ * </p>
  *
  * <pre>
- *   Amadeus amadeus = Amadeus.builder("CLIENT_ID", "CLIENT_SECRET").build();
+ * Amadeus amadeus =
+ *     Amadeus.builder("REPLACE_BY_YOUR_API_KEY", "REPLACE_BY_YOUR_API_SECRET").build();
  * </pre>
  *
- * <p>Or pass in environment variables directly:</p>
+ * <p>
+ * Or pass in environment variables directly:
+ * </p>
  *
  * <pre>
- *   Amadeus.builder(System.getenv()).build();
+ * Amadeus.builder(System.getenv()).build();
  * </pre>
  */
 public class Amadeus extends HTTPClient {
@@ -24,24 +29,21 @@ public class Amadeus extends HTTPClient {
 
   /**
    * <p>
-   *   A namespaced client for the
-   *   <code>/v2/reference-data</code> endpoints.
+   * A namespaced client for the <code>/v2/reference-data</code> endpoints.
    * </p>
    */
   public ReferenceData referenceData;
 
   /**
    * <p>
-   *   A namespaced client for the
-   *   <code>/v1/travel</code> endpoints.
+   * A namespaced client for the <code>/v1/travel</code> endpoints.
    * </p>
    */
   public Travel travel;
 
   /**
    * <p>
-   *   A namespaced client for the
-   *   <code>/v1/shopping</code> endpoints.
+   * A namespaced client for the <code>/v1/shopping</code> endpoints.
    * </p>
    */
   public Shopping shopping;
@@ -54,14 +56,13 @@ protected Amadeus(Configuration configuration) {
   }
 
   /**
-   * Creates a builder object that can be used to build
-   * an Amadeus com.amadeus.client.
+   * Creates a builder object that can be used to build an Amadeus com.amadeus.client.
    *
    * <pre>
    * Amadeus amadeus = Amadeus.builder("CLIENT_ID", "CLIENT_SECRET").build();
    * </pre>
    *
-   * @param clientId Your API com.amadeus.client credential ID
+   * @param clientId     Your API com.amadeus.client credential ID
    * @param clientSecret Your API com.amadeus.client credential secret
    * @return a Configuration object
    */
@@ -70,8 +71,8 @@ public static Configuration builder(@NonNull String clientId, @NonNull String cl
   }
 
   /**
-   * Creates a builder object initialized with the environment variables that can be used to
-   * build an Amadeus API com.amadeus.client.
+   * Creates a builder object initialized with the environment variables that can be used to build
+   * an Amadeus API com.amadeus.client.
    *
    * <pre>
    * Amadeus amadeus = Amadeus.builder(System.getenv()).build();

src/main/java/com/amadeus/Configuration.java

@@ -7,26 +7,29 @@
 import lombok.ToString;
 import lombok.experimental.Accessors;
 
-
 /**
- * <p>The configuration for the Amadeus API client. To initialize, use the builder as follows:</p>
+ * <p>
+ * The configuration for the Amadeus API client. To initialize, use the builder as follows:
+ * </p>
  *
  * <pre>
- *   Amadeus amadeus = Amadeus.builder("CLIENT_ID", "CLIENT_SECRET").build();
+ * Amadeus amadeus =
+ *     Amadeus.builder("REPLACE_BY_YOUR_API_KEY", "REPLACE_BY_YOUR_API_SECRET").build();
  * </pre>
  *
- * <p>Or pass in environment variables directly:</p>
+ * <p>
+ * Or pass in environment variables directly:
+ * </p>
  *
  * <pre>
- *   Amadeus.builder(System.getenv()).build();
+ * Amadeus.builder(System.getenv()).build();
  * </pre>
  */
 @Accessors(chain = true)
 @ToString
 public class Configuration {
-  private static final Params HOSTS = Params
-          .with("production", "api.amadeus.com")
-          .and("test", "test.api.amadeus.com");
+  private static final Params HOSTS =
+      Params.with("production", "api.amadeus.com").and("test", "test.api.amadeus.com");
 
   /**
    * The client ID used to authenticate the API calls.
@@ -48,24 +51,22 @@ public class Configuration {
    */
   private @Getter @Setter Logger logger = Logger.getLogger("Amadeus");
   /**
-   * The log level. Can be 'silent', 'warn', or 'debug'.
-   * Defaults to 'silent'.
+   * The log level. Can be 'silent', 'warn', or 'debug'. Defaults to 'silent'.
    *
    * @param logLevel The log level for the logger
    * @return The log level for the logger
    */
   private @Getter @Setter String logLevel = "silent";
   /**
-   * The the name of the server API calls are made to, 'production' or 'test'.
-   * Defaults to 'test'
+   * The the name of the server API calls are made to, 'production' or 'test'. Defaults to 'test'
    *
    * @param hostname The name of the server API calls are made to
    * @return The name of the server API calls are made to
    */
   private @Getter String hostname = "test";
   /**
-   * The optional custom host domain to use for API calls.
-   * Defaults to internal value for 'hostname'.
+   * The optional custom host domain to use for API calls. Defaults to internal value for
+   * 'hostname'.
    *
    * @param host The optional custom host domain to use for API calls.
    * @return The optional custom host domain to use for API calls.
@@ -79,24 +80,21 @@ public class Configuration {
    */
   private @Getter boolean ssl = true;
   /**
-   * The port to use. Defaults to 443 for an SSL connection, and 80 for
-   * a non SSL connection.
+   * The port to use. Defaults to 443 for an SSL connection, and 80 for a non SSL connection.
    *
    * @param port The port to use for the connection
    * @return The port to use for the connection
    */
   private @Getter @Setter int port = 443;
   /**
-   * An optional custom App ID to be passed in the User Agent to the
-   * server (Defaults to null).
+   * An optional custom App ID to be passed in the User Agent to the server (Defaults to null).
    *
    * @param customAppId An optional custom App ID
    * @return The optional custom App ID
    */
   private @Getter @Setter String customAppId;
   /**
-   * An optional custom App version to be passed in the User Agent to the
-   * server (Defaults to null).
+   * An optional custom App version to be passed in the User Agent to the server (Defaults to null).
    *
    * @param customAppVersion An optional custom App version
    * @return The optional custom App version
@@ -119,16 +117,15 @@ public Amadeus build() throws NullPointerException {
   }
 
   /**
-   * The the name of the server API calls are made to, 'production' or 'test'.
-   * Defaults to 'test'.
+   * The the name of the server API calls are made to, 'production' or 'test'. Defaults to 'test'.
    *
    * @param hostname The name of the server API calls are made to
    * @return The name of the server API calls are made to
    */
   public Configuration setHostname(String hostname) {
     if (!HOSTS.containsKey(hostname)) {
       throw new IllegalArgumentException(
-              String.format("Hostname %s not found in %s", hostname, HOSTS.keySet().toString()));
+          String.format("Hostname %s not found in %s", hostname, HOSTS.keySet().toString()));
     }
     this.hostname = hostname;
     this.host = HOSTS.get(hostname);