Project Overview

 

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

Challenge Overview

In this challenge you are building a iOS Mobile SDK for UtilityAPI.

Challenge Requirements

You will address the following in this challenge :

The SDK will be a Cocoa Touch Framework project with following requirements :

1. All XCode projects you are implementing in this project should be put in a single XCode Workspace.

2. The code should be written in Swift programming language.

3. We would like to follow the structure of forcedotcom project :

   1. Libs folder includes the core SDK projects that communicate with the UtilityAPI

   2. For External and ThirdPartyDependencies folders, should be added to your solution if we need to use a 3rd party frameworks and libraries that need to referenced by the core SDK framework.

   3. You need to write a shell script (similar to ./install.sh in SF SDK) to install these 3rd party frameworks and libraries.

4. README file, read below about it’s content details.

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

   1. GET /accounts - get a list of accounts

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

   3. POST /accounts/add - add an account

   4. GET /accounts/<uid> - get an account object

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

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

   7. POST /accounts/<uid>/modify - modify the account

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

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

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

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

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

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

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

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

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

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

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

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

6. Notes about the Wrapper SDK :

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

   2. So we recommend also following the Salesforce sdk structure :

      1. Build generic REST classes that handle the logic to communicate with the API : RESTAPI, RESTRequest, and RESTResponse .. etc.

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

         • AccountsAPI

         • ServicesAPI

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

7. Additional SDK Functionality - Add a function in AccountsAPI for “Create Account”

   1. 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.

   2. Input to the function is user credentials used to create account, and a callback function parameter.

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

      1. GET /accounts/add

      2. POST /accounts/add

      3. 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.

      4. GET /services?accounts=123

      5. POST /services/456/modify (change “active_until”)

      6. GET /services/456

         • 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.

      7. GET /services/456/bills

      8. When complete, execute callback function passing back relevant data

8. Write XCTests for all Core SDK Code.

   1. You must cover at least 85% of the code.

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

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

   2. 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

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

   4. Running Tests - this should details how to setup and run the tests. It is important section to verify the SDK setup is correct.

   5. 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

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

   7. 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.

10. 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.

11. You must follow the coding standards for the swift language.

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 using the Invite Code posted in challenge forums 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

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

Final Submission Guidelines

Deliverables

• XCode Workspace that includes all the XCode Projects that implement the above requirements

• README.md (Markdown formatting) file as detailed above.

• Install and Build scripts