Challenge Overview
Background of the API
With more than 60 APIs, HPE Haven OnDemand makes it quick and easy for developers to apply the power of machine learning to their apps using text analysis, speech recognition, image analysis, prediction, indexing and search APIs. Learn more here, follow @havenondemand on Twitter and on Instagram for the latest news, event updates and more, and join the HPE Haven OnDemand Developers group on LinkedIn for professional networking. Create an account to get your API key and free monthly quota (this quota is sufficient to meet the requirements for this challenge). Paid plans are now available and start at $10/month. Details on pricing are available here.
API questions? Check out the Haven OnDemand documentation and forum.
Challenge related questions? Please use the TopCoder forum for this challenge.
R client library - POST Requests
In order to make it easy for R developers to add Haven OnDemand functionality to their apps, we would like the TopCoder community to help build a new R client library. We’re breaking this challenge into two separate challenges which when combined will produce the entire R client library. This first challenge will focus on creating the part of the client library responsible for making POST requests to the APIs, checking on the status of an asynchronous request, and the response parser. 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:
Order suggestion on how to approach this
(This will make more sense once you read this entire spec).
-
Initializer for the client
-
Methods for performing POST requests
-
Methods for performing POST requests with files
-
Method for checking status of async request
-
Response parser
-
README
Requirements:
- Create initializer for the client library
- Create method(s) for performing the POST request
- Create method for checking the status of async requests (see this for help)
- Publish to Github
- Create a response parser (see this example)
- 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
* https://github.com/HPE-Haven-OnDemand/havenondemand-salesforce
- 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 request a POST, followed by the code to do it
curl -X POST --form "url=https://www.havenondemand.com/sample-content/documents/IDOLbrochure.pdf" --form "extract_metadata=true" --form "extract_text=true" --form "extract_xmlattributes=false" --form "apikey=API_KEY" https://api.havenondemand.com/1/api/sync/extracttext/v1
* POST request of files, for APIs that accept files, followed by the code to do it
* how to parse out the response followed by the code to do it
- 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 PostRequest(ref Dictionary<String, Object> Params, String hodApp, REQ_MODE mode), and the GetJobStatus(String jobID), and the API callback functions, if applicable.
- Include detailed instructions for integrating the HODClient into an R 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 POST request
* Asynchronous POST request
* How to parse responses from Haven OnDemand
* How to Add to Text Index
- 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 R developers to use.
* 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. For example, the code which post files through multipart post should be extracted into a common code unit and abstracted from API calls themselves.
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.
Final Submission Guidelines
Submission requirements:
-
You should use R. You are creating an API interface for other developers to use.
-
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
Getting started
