Challenge Overview
Getting Started
Background of the API
HPE Haven OnDemand is a cloud-native platform with 60+ APIs for developers to build data rich applications and perform analytics using text analysis, speech recognition, image analysis, prediction, indexing and search APIs. Add advanced capabilities such as natural language processing, machine learning, cognitive computing, and predictive analytics to your application with minimal coding and effort.
Crawl, index and analyze data from file systems, DropBox, and the web. Analyze and extract insights from documents, text, audio, video, and image files, or build your own prediction and recommendation engines. By combining APIs you’ll be able to create powerful data transformation and enrichment workflows.
Force.com client library - POST 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 a new Force.com client library. We’re breaking this challenge into two separate challenges which when combined will produce the entire Force.com 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 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:
- Ruby
- Swift
- Android
- Node.js
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
- Mock Tests
- 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
- 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 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 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 POST request
- Asynchronous POST request
- How to parse responses from Haven OnDemand
- How to Add to Text Index
- Mock tests should be written for the following endpoints: Speech Recognition, Text Extraction, and the set of Prediction 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 pass and make mock API calls to Haven OnDemand.
- Ensure that there are no restrictions or dependencies that aren't appropriate for a more generalized library.
- Some APIs involve getting multipart post REST functionality. Those methods are storeObject, expandContainer, and textExtraction.
- 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 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