Note – all work done for this challenge must be completed and added onto the winning submission of the previous challenge in this series. Please clone/download this repository and use this as the base when writing code for the current challenge. This challenge and the previous, when combined, are intended to produce a fully functioning API wrapper. Any submission that does not follow this will NOT be accepted.

Background of the API

HPE Haven OnDemand is a platform for building cognitive computing solutions and data rich applications using text analysis, speech recognition, image analysis, indexing and search APIs.

Force.com client library - GET requests

In order to make it easy for Force.com developers to add Haven OnDemand functionality to their apps, we would like the TopCoder community to help build our Force.com client library. We’re breaking this challenge into two separate challenges which when combined with the previous challenge, will produce the entire Force.com client library. The source code from the winning submission of first challenge is available in repo mentioned above. This second challenge will focus on creating the part of the client library responsible for making GET requests to the APIs, checking on the result of an asynchronous request,  and creating mock tests for the more popular endpoints. The documentation of the client should describe the integration of the library, explain the syntax of each function, and include some image illustrations, if necessary, as needed to help explain key concepts.

What is a client library?

 

A client library is a “wrapper” to make HTTP requests to a particular API, in a particular software language. Client libraries are provided by API companies to minimize the amount of time and effort required to integrate the platform into a project by providing prepackaged tools to make requests to the API.

 

For examples of client libraries in other software languages, see these:

 

• https://github.com/HPE-Haven-OnDemand/havenondemand-ruby

• https://github.com/HPE-Haven-OnDemand/havenondemand-ios-swift

• https://github.com/HPE-Haven-OnDemand/havenondemand-windows-8.1-universal

• https://github.com/HPE-Haven-OnDemand/havenondemand-android

Order suggestion on how to approach this

 

(This will make more sense once you read this entire spec).

 

1. Initializer for the client

2. Methods for performing GET requests

3. Method for checking the result of async request

4. Tests

5. README

 

Requirements:

- Create method(s) for performing the GET request

- Publish to Github

- README drafted using markdown

- Use the correct product name HPE Haven OnDemand where applicable

- Use the correct API names where applicable e.g. Entity Extraction for https://dev.havenondemand.com/apis/extractentities#overview

- Use the most recent version 2 endpoints for making Haven OnDemand API calls e.g. https://api.havenondemand.com/1/api/sync/extractentities/v2 by adding an optional parameter when making requests or constructing the client  to specify the version number; if no version number is specified, have it default to ‘v2’

- Model the naming conventions and structure of the client library off these official examples

            - https://github.com/HPE-Haven-OnDemand/havenondemand-ruby

            - https://github.com/HPE-Haven-OnDemand/havenondemand-ios-swift

            - https://github.com/HPE-Haven-OnDemand/havenondemand-windows-8.1-universal

            - https://github.com/HPE-Haven-OnDemand/havenondemand-android

            - https://github.com/HPE-Haven-OnDemand/havenondemand-node

 

- Explanations and details of the library structure and syntax with code samples

          - how to download it followed by the code to do it

          - how and where to import it into your app followed by the code to do it

          - how to send a GET request followed by the code to do it

          - curl “https://api.havenondemand.com/1/api/sync/extracttext/v1?url=https%3A%2F%2Fwww.havenondemand.com%2Fsample-content%2Fdocuments%2FIDOLbrochure.pdf&additional_metadata=&extract_metadata=true&extract_text=true&extract_xmlattributes=false&apikey=API_KEY"

- README.md

           - ‘Demo codes’ are great at the end, but they need some context beforehand to make it easier for someone who is just coming to the page and doesn’t know our API that well. Ideally, developers should be able to copy and paste from the README and  have a working app in minutes without having to Google anything about iOS, Andriod, or Windows mobile development. Keep in mind, these READMEs are read by beginners who are still figuring out the fundamentals, so try and put yourself in their shoes when reading it and making alterations

- Make all code into code blocks, like this one, for example - HODClient(string apiKey, String version="v1”). For help with markdown, reference this cheat sheet. This can be done by encasing it within these tick marks - `` - for one liners. For larger code blocks spanning multiple lines, encase them within three tick marks in the beginning, followed by the language of the client library is written in, adding a new line with code sample, then adding another three at the end. Example, in Ruby:

        ```ruby

client = HODClient.new(apikey, version)

```

- Provide an example for each of the other code blocks, so show them a working, small example (much shorter than the demos at the end, should be as bare bones as possible) of the GetRequest(ref Dictionary<String, Object> Params, String hodApp, REQ_MODE mode), the GetJobResult(String jobID), and the API callback functions.

- Include detailed instructions for integrating the HODClient into a Force.com project

- Include copy and paste demo code examples, with prefacing content so that a developer coming to the page does not have to reverse engineer anything. Demos should cover:

        - Synchronous GET request

        - How to parse responses from Haven OnDemand

         - Query text index example

         - Mock tests should be written for the following endpoints: Sentiment Analysis, OCR Document, and Concept Extraction APIs

 

- Hello world demo app: include a simple “Hello world” demo app that uses the new client library.

        - Develop an unmanaged code package which contains the HODApi and HTTPClient classes and the other classes required support the basic functionality to make IDOL API REST requests and parse responses.  You should include Utility classes as required in the library but some classes may need to be refactored to remove Case-specific functionality.  No controller classes or VF pages should be included in our final product.  You're creating a Haven OnDemand library here for other Force.com developers to use.

        - Create test class and methods which validate the functionality of each HODApi function.  All your tests should not only pass but make actual API calls to IDOL OnDemand.

        - Ensure that there are no restrictions or dependencies that aren't appropriate for a more generalized library.

        - Wherever possible please reduce duplication in the code to produce clean readable code.

 

Tips and tricks:

         - Adding images to .md - http://stackoverflow.com/questions/14494747/add-images-to-readme-md-on-github. Host the images in a folder in the github repo so you don’t have to put it in an external site like AWS.

          - Again, model these READMEs after the examples provided. If there are useful bits and pieces that you think will help explain things, then add them in as well.

Getting started

Final Submission Guidelines

• You should use Visualforce and Apex. You are creating an API interface for other developers to use.

• You may use Bootstrap and/or JQuery javascript libraries.

• Please provide your submission as an unmanaged package for evaluation

• Include a tutorial blog post describing how to use the client library including a short screencast that supports this tutorial (make the video available as an .mp4 file )e.g. https://community.havenondemand.com/t5/Blog/Up-and-running-in-5-minutes-with-Haven-OnDemand-using-Node-js/ba-p/1968