Say Hello to Trolley’s Full Featured SDKs

Did you know Trolley offers SDKs in 6 different programming languages? This post looks at the Trolley SDKs, which can help your team move fast with your integration with our API.

Trolley APIs allow our customers to integrate Trolley directly into their systems. However, integrating any API requires writing a lot of code oneself, which can often extend the time needed to build the integration. This is where Trolley’s SDKs come in handy, significantly reducing the amount of manual coding.

Trolley’s SDKs are offered in 6 different programming languages: Javascript, Ruby, PHP, Python, Java, and .Net (C#).

In this post, we’ll see how, through an example, our SDKs reduce the effort, their API coverage, and where to find them.

The Value of Trolley’s SDKs  

When making an API call, multiple steps are performed, many of which multiple times, throughout the codebase (network requests, parsing of responses, etc.)

When using our SDKs, Trolley users avoid this duplication of effort, speeding up overall integration time. Using the SDKs also reduces the chances of running into API errors, letting you focus on other things that really matter.

Let’s compare fetching all recipients via an API call manually coded in Java and then the Trolley Java SDK to see how our SDKs can reduce the effort.

      ...
      //API Call using Java
      try{
      // Compute auth signature
      HashMap<String,String> headerValues = new HashMap<String, String>();
          
      int timeStamp = (int) (System.currentTimeMillis() / 1000L);

      String message = timeStamp + "\n" 
      + "GET" + "\n" 
      + "/v1/recipients" + "\n" 
      + "" + "\n";

      String digest = null;
      final SecretKeySpec key = new SecretKeySpec((SECRET_KEY).getBytes("UTF-8"), "HmacSHA256");
      Mac mac = Mac.getInstance("HmacSHA256");
      mac.init(key);

      byte[] bytes = mac.doFinal(message.getBytes("ASCII"));

      StringBuffer hash = new StringBuffer();
      for (int i = 0; i < bytes.length; i++) {
          String hex = Integer.toHexString(0xFF & bytes[i]);
          if (hex.length() == 1) {
              hash.append('0');
          }
          hash.append(hex);
      }
      digest = hash.toString();

      headerValues.put("Authorization", "prsign " + ACCESS_KEY.toString() + ":" + digest);
      headerValues.put("X-PR-Timestamp", ""+timeStamp);
      headerValues.put("Content-Type", "application/json");

      // Prepare API request
      URL obj = new URL("https://api.trolley.com/v1/recipients");
      HttpURLConnection con = (HttpURLConnection) obj.openConnection();
      con.setRequestMethod("GET");

      //Setting header values
      for (String i : headerValues.keySet()) {
        con.setRequestProperty(i, headerValues.get(i));
      }

      // Read Network Response
      BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()));
      String inputLine;
      StringBuffer response = new StringBuffer();

      while ((inputLine = in.readLine()) != null) {
        response.append(inputLine);
      }
      in.close();

      //Parse response JSON to POJO for consumption
      final ObjectMapper mapper = new ObjectMapper();
      mapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
      final JsonNode node = mapper.readTree(response.toString());

      final List<Recipient> recips = (List<Recipient>)mapper.readValue(node.get("recipients").traverse(), (Class)Object.class);

      final Meta meta = (Meta)mapper.readValue(node.get("meta").traverse(), (Class)Meta.class);

      final Recipients recipients = new Recipients(new ArrayList<Recipient>(), meta);

      for (int i = 0; i < recips.size(); ++i) {
        final Recipient pojo = (Recipient)mapper.convertValue((Object)recips.get(i), (Class)Recipient.class);
        recipients.getRecipients().add(pojo);
      }

      //Use parsed response
      System.out.println(recipients.getRecipients().size());
      }catch (UnsupportedEncodingException e) {
          e.printStackTrace();
      }catch (InvalidKeyException e) {
          e.printStackTrace();
      }catch (NoSuchAlgorithmException e) {
          e.printStackTrace();
      }catch (IOException e) {
          e.printStackTrace();
      }
      ...

      ...
      //Initialize the Java SDK
      Configuration config = new Configuration("<ACCESS_KEY>","<SECRET_KEY>");
      Gateway client = new Gateway(config);

      // List all recipients and auto-paginate through the results 
      RecipientsIterator recipients = client.recipient.search("<optional_search_term>");

      while(recipients.hasNext()) {
        System.out.println(recipients.next().getId());
      }

      ...

As you can see, from 70+ lines of code trying to access Trolley APIs with plain Java to less than 10 using Trolley’s Java SDK.

Additionally, the SDKs try to extend some functionalities and make things even easier for you. For example, the SDK sample code auto-paginates, so that you don’t have to do it on your own.

These steps help our customers focus on building integration features rather than figuring out how to get API calls working.

While there will still be cases where you will want to use our APIs directly to build even more complex user flows and experiences, the SDKs will significantly reduce the effort in handling the rest.

SDK Coverage  

We have spent a fair amount of effort throughout 2023, releasing major updates to all our SDKs. All of our SDKs are at parity with our public APIs, covering all potential endpoints and features.

Going forward, all SDKs will cover new API endpoints/updates as they become available.

Documentation and Sample Code  

The documentation available at developers.trolley.com  contains API documentation, request & response samples, and code samples for all different SDKs.

So, for most actions, you can copy the code samples from the documentation and adapt them according to you needs.

Trolley SDKs and where to find them  

All our SDKs are available from the leading package managers of the respective programming languages.

Here’s a list detailing where to find the SDKs and how to install them

Javascript SDK  

Ruby SDK  

PHP SDK  

Python SDK  

C# .Net SDK  

Java SDK  

    <dependency>  
      <groupId>com.trolley</groupId>  
      <artifactId>java-sdk</artifactId>  
      <version>{LatestVersion}</version>  
    </dependency>

Conclusion  

Having more options when it comes to integrating with Trolley will always give more flexibility. We strongly believe using the SDKs will make one’s Trolley integration quicker and more predictable.

Trolley developers often integrate Trolley services deeply with their systems, as I have observed personally. My hope is that this article will display the value the SDKs can bring, and show how to get started with them.

All of our SDKs are open-sourced, and if you have any improvements, we welcome pull requests.

For any other questions or if your team faces any issues, write to us at developers@trolley.com.