SunShot - UtilityAPI Ruby SDK Development [Bonus Payments]

Project Overview

UtilityAPI is an api that automatically downloads bill and usage data from electric utilities.

Challenge Overview

In this challenge you are building an Ruby SDK for UtilityAPI.

Challenge Requirements

API Endpoints Requirements

• Here's the list of API endpoints to be covered in the SDK :

  • GET /accounts - get a list of accounts

  • GET /accounts/add - get the options for adding an account (i.e. what utilities are available)

  • POST /accounts/add - add an account

  • GET /accounts/<uid> - get an account object

  • GET /accounts/<uid>/auth.zip - get the account authorization file (if not direct authorization)

  • GET /accounts/<uid>/modify - get options for modifying the account

  • POST /accounts/<uid>/modify - modify the account

  • GET /accounts/<uid>/delete - get a deletion code for the account

  • POST /accounts/<uid>/delete - delete the account and all services and data for that account

  • GET /services - get a list of utility services (i.e. list of meters)

  • GET /services/<uid> - get a specific service object

  • GET /services/<uid>/bills - get the bills for a service

  • GET /services/<uid>/bills.zip - get the raw bills for a service

  • GET /services/<uid>/bills/<filename> - get a specific raw bill

  • GET /services/<uid>/intervals - get the intervals for a service

  • GET /services/<uid>/modify - get options for modifying a service

  • POST /services/<uid>/modify - modify a service (i.e. activate or deactivate)

  • GET /services/<uid>/reset - get a deactivate-and-forget-data code for a service

  • POST /services/<uid>/reset - deactivate and forget data for a service

• Additional SDK Functionality - Add a function in new class (AccountsUtilities) for “Create Account”

  • This function should combine all the calls provided by the API to set up a new account.

  • It should be able to run asynchronously, as the creation process will involve some waiting.

  • It should accept a callback function because certain calls out will take a little while to return response.

  • Input to the function is user credentials used to create account.

  • The flow will execute each one of these endpoints (sequential execution) :

    • POST /accounts/add

    • GET /accounts/{id}

      • It may take a while to have Account [“latest”][“type”] != “pending” so you need to wait until it becomes ‘updated’ then move to next endpoint execution.

    • GET /services?accounts=123

    • POST /services/456/modify (change “active_until”)

    • GET /services/456

      • It may take a while to have Service [“latest”][“type”] != “pending” so you need to wait until it becomes ‘updated’ then move to next endpoint execution.

    • GET /services/456/bills

    • When complete, execute callback function passing back relevant data

• Write a detailed README.md file (using markdown language) that covers the following :

  • What is this? - An overview of the project and the SDK

  • Prerequisites - This section should details the steps and setup needed to be done before starting using the SDK. i.e. obtain API keys, setup sandbox, or setup/install a 3rd party software/library .. etc

  • Building the SDK - This should details the steps needed to build the core, and native libraries.

  • Including the SDK in your project - This section should explain how to include the SDK in developer IDE, and how to install it. i.e. download SDK, include path in environment variables, update project configurations, execute specific commands from terminal ..etc

  • Sample Usage of OAuth - This should talk about how to create access token, and how to pass it in the SDK calls.       

  • Usage (Snippet code) - This section should show usage snippet of different parts of the SDK, we should cover the main parts. one endpoint of each API endpoints group.

• Make sure all API calls are consistent. Either append .json to all requests (the api default returns .html) or set the content type in the header request to be of type json.

• The API Based URL is https://utilityapi.com/api/ (make it configurable)

Ruby API Client Framework

There are a number of HTTP client gems out there such as Typhoeus, Faraday and httparty. The standard library includes Net::HTTP, however it isn't very straightforward to use.

It is up to you to pick up an existing gem library or do it from scratch.

Abstracting and Design

• Please make sure to create mixin to include the common code/functionality.

• Your solution should support future extensibility, adding/removing api should not result into too much effort and code refactoring.

• So we recommend the following :

  • Build generic REST classes that handle the logic to communicate with the API.

  • Each endpoint group should have it’s own Class that delegate the API calls to the generic REST classes :

    • AccountsAPI

    • ServicesAPI

Setting Up the Gem

It is recommend to use Bundler to take care of gem dependencies.

A standard folder structure would look like this :

• Gemfile

• LICENSE.txt

• README.md

• Rakefile

• utilityapi.gemspec

• lib

  • utilitysdk

    • version.rb

    • model

      • <model-name>.rb

    • <api-wrapper-name>.rb

Writing Tests

All of your code should be test covered (RSpec preferred). You must cover at least +90% of the code.

Documentation

Because other programmers will be working with your code, and incorporating it into their projects, all functions must be documented in detail in the code (TomDoc preferred - In order to generate HTML properly you will need to use Yard TomDoc).

Coding Standard

Follows coding standards listed here: https://github.com/copycopter/style-guide

Readme

Provide a detailed readme file using Markdown language with following information :

• Overview

• Setup Prerequisites

• How to install

• Usage Example

• Reference to API Documentation

• Reference to the Ruby Gem Documentation

• Any details about any limitations of your solution.

Please note, we're judging this competition not just on the code, but also on the quality of the documentation, test coverage, and ease of use.

Documentation

• Utility API Documentation

• Note: You must create an account with Utility API to view the documentation.

Get Started in Utility API

1. Create Account https://www.utilityapi.com/api/users/new.html

2. Login

3. Go to settings (Use top right corner gear to navigate to settings page)

4. In Tokens table add new token of type API

5. In services page add new service of type demo https://www.utilityapi.com/api/services.html

Verify that you can call the API properly https://www.utilityapi.com/api/accounts/add.json?access_token=<ACCESS_TOKEN>

Final Submission Guidelines

Deliverables

• All source code files and scripts that addresses the challenge requirement.

• Detailed readme file as clarified above.