• Compete
  • Learn
  • Community

    SunShot - UtilityAPI Swift iOS SDK







    POINTS: 630

    The challenge is finished.
    Show Deadlines icon-arrow-up

    Challenge Overview

    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.


    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


    • 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

    Reliability Rating and Bonus

    For challenges that have a reliability bonus, the bonus depends on the reliability rating at the moment of registration for that project. A participant with no previous projects is considered to have no reliability rating, and therefore gets no bonus. Reliability bonus does not apply to Digital Run winnings. Since reliability rating is based on the past 15 projects, it can only have 15 discrete values.
    Read more.


    2015 topcoder Open


    Final Review:

    Community Review Board



    User Sign-Off