iCity Developer Guide


Getting started with the API portal


About the portal


Logging in

To log in to the API Portal, open your web browser and navigate to the following address: http://icity-devp.icityproject.com.

Click Login at the top of the browser window and then enter your Username and Password (if you do not have a login, please singup).
To find more info on the Registration Process Scenario, click the link on our documentation page.

The Dashboard is displayed:





Working with the Dashboard


  • The Dashboard is the interface for developers.

  • Each individual user can personalize the Dashboard.

  • Once you log in, the Dashboard page is displayed by default. You can quickly reutrn to the Dashboard at any time by clicking the Dashboard link below the Welcome message at the top of browser.

    Customize your Dashboard widgets




    From the Dashboard, click [+WIDGETS] to open the widget area.       

  • To add a widget, drag into the Dashboard area.
          
  • To remove a widget, click [X] on the top left corner of the widget.
          
  • To configure a widget, point to the widget title and then click the gear icon on the right side of the title bar. Every widget has its own configuration settings.

    Click[Done] to save the configuration changes.
    When you have finished customizing your Dashboard, click [-WIDGETS] to close the widget area.

    Administrators can set which dashboard widgets are active. The widgets available in the Dashboard section are detailed in the following lines:

  • Messages: This section shows the messages that a developer received from an Administrator or Manager User.
          
  • My APPS: List of applications created by the developer with their availability to access to APIs.
          
  • Latest API Docs: List of latest documents uploaded to the portal.

    Updating Account Information


    To change the icon displayed beside the Dashboard link:
          
  • From within My Profile, click [Choose File]. A file upload dialogue box displays.
          
  • Locate a jpeg/jpg file on your local system and click [Open]. The file is uploaded to the API Portal.
          
  • Click [Save]. The icon beside the Dashboard link is updated with your file.


    Developers can change their own passwords via the Manage My Profile

    Your personal account information can be changed at any time - for example, to reset your login and password information.
    To update your account information:       

  • From the Dashboard, select My Profile from the navigation sidebar.
          
  • Update the fields as required. Note that if you want to change the password, you must also enter your current password.
          
  • Click [Save] when done.
    Note: You will need to click on a link before the uploaded icon is displayed



          
  • Log in to the iCity API Portal.
          
  • Click My Profile in the navigation sidebar.
          
  • Enter your current password in the Current Password field.
          
  • Enter the new password in both the New Password and Re-Enter your password fields.
          
  • Click [Save] when you are done.


    Reporting


    Developer Reports


    Developers have access to both application reports and API reports. In addition, each report offers two views located on two separate tabs: Usage and Latency.

    The API reports allow developers to:
          

  • View usage for an API:Select an API from the API drop-down (note that the API drop-down will be populated only with APIs to which the developerhas access). The graph shows hits against that API.
          
  • Top Graph:Shows total hits against the API from all the developer's applications.
          
  • Middle Graph: Shows, of the total hits, how many successfully received a reply (i.e., resulted in a successful transaction).
          
  • Bottom Graph:Shows, of the total hits, how many did not receive a reply (i.e., resulted in an error).
          
  • View latency for an API:Select an API from API drop-down. The graph shows average latency of the API for all the developer's applications.
          
  • Top graph: Shows the total, round trip time for an application request to enter the API Proxy, go to the back-end API(s), and then pass back through the API Proxy.
          
  • Bottom Graph:Shows the time it takes for a request to be processed by the API Proxy.



    The Application reports allow deveolpers to:
          

  • View usage for an application:Select an application from Application drop- down. The graph shows total API queries/requests (a.k.a. "hits") for that application.
          
  • Top Graph:Shows all hits against all the APIs the application uses.
          
  • Middel Graph:Shows, of the total hits, how many successfully received a reply (i.e., resulted in a successful transaction).
          
  • Bottom Graph:Shows, of the total hits, how many did not receive a reply (i.e., resulted in an error).
        
  • View latency for an application: Select an application from Application drop- down. The graph shows average latency for that application.
          
  • Top Graph:Shows the time it takes for an application request to enter the API Proxy, get passed to the back-end API(s), and then leave the API Proxy.
          
  • Bottom Graph:Shows the time it takes for a request to be processed by the API Proxy.




    Usage Reports


    This pages provides a high level view of Account Plan usage by organization.
    To view usage reports:

  • From the Dashboard, select Analytics > Usage Reports from the navigation sidebar. The Usage Reports page displays.



    In the Choose Range drop-down, select the date range, from Last 24 hours, Last 7 days, Last 30 days, and Last 365 days. Alternatively, you may select specific dates in the From and To fields.

    If you belong to more than one organization, choose the organization to report on from the Organization drop-down.

    Click [Generate Reports] to view the report.



    Developer Functionality


    This section describes how developers will use the API Portal.The first developer to register for your organization will also have the role of Organization Admin.

    Developer Roles


    The following "Developer" user roles are preconfigured on the iCity API Portal:

  • OrgAdmin:The owner of an organization. This is typically a third-party user that signs up for an account on the iCity API Portal using the Registration Form. This person is responsible for managing his or her own organization and is usually the only developer or the first one to register for the organization.
          
  • Developer:A user that has been invited to join the iCity API Portal by an organization owner (OrgAdmin). These users are enrolled under the OrgAdmin's account. Developers are responsible for creating and managing new applications.

    Register for an Account


    The first thing developers need to do is register for an account. They do this by signing up on the iCity API Portal and completing a registration form.


    Note: The iCity API Portal does not permit registration of duplicate organization names. As a result, once the first developer from an organization has registered an account with the portal, subsequent developers from that same organization require an invitation to be registered.

    To register an account

    On the API Portal home page, click Signup in the upper right corner. Complete the registration dialogue as follows. Tip: Advance to the next tab either by clicking [Next Step] or by clicking the tab title.


    Note: Administrators can configure which tabs are available on the registration dialogue so not see all of the tabs described below may be visible.


    Click [Register Now]. If registrations are subject to approval, the developer will receive an email stating that the account is under review. Otherwise, the developer will be emailed a link to click on in order to activate the account.


    Tip: If the email does not appear in the developer's inbox, advise them to check their junk mail folder.

    Each new developer has assigned a default Account Plan when they finish the registration process. An Account Plan determines the number of queries (hits) that each user can make to any existing applications.

    For example, the default one (Bronze Account Plan) allows doing 10000 hits per day.

    Each user can request an upgrade of Account Plan depending on their needs, increasing the value of the threshold's quota.

    Add New Applications


  • Log in to the iCity API Portal.
          
  • From the Dashboard, select Applications in the navigation sidebar. The list of your applications displays.
          
  • Click [Add Application]. This displays an application wizard with tabs.
          
  • Complete the application information as follows. Click [Next Step] when each tab is completed, or click the tab name to move between tabs:

          


    Manage Applications


    Developers can add, edit, enable, disable, or delete their applications via the Manage Applications page.
    The Manage Applications page also allows you to view your organization's Account Plan quotas and the API Plan assigned to each application.

    Each new Application has assigned a default API Plan when the application has been enabled. An API Plan determines the number of queries (hits) that each application can make to their assigned APIs.

    For example, the default one (Sandbox API Plan) provides an appropriate API service level for developers who are starting to build an application.

    Developers can request a different API Plan (for example), when they move their application into test or production.

    To enable, disbale or delete yout applications

  • Log in to the iCity API Portal as a developer or OrgAdmin.
          
  • From the Dashboard, select Applications in the navigation sidebar. The list of your applications displays.
          
  • Hover over the appropriate application.
          
  • Select the appropriate action Delete, Disable, or Enable from the drop-down menu of the gear icon.
          
  • Click [OK] to confirm.


    Note: If an application is Pending Approval, you can view more information about it by selecting View from the drop-down menu of the gear icon.

    IMPORTANT: Deleting an application makes all report history for that application irretrievable. If Account Plan Quotas are in effect, API hits made via an application prior to deletion will continue to count toward the Account Plan Quota, even though these hits won't be shown in the report. iCity recommends disabling applications instead of deleting them to maintain report accuracy.


    Edit Applications


    Developers can edit their applications via the Manage Applications page.

    They can also add, edit, enable, disable, or delete them.

    If a new application has been rejected, its status will appear as Rejected in the list of applications and the details of its rejection will appear in an email. When you edit the application and save your changes, the application will be resubmitted and will display a status of Revised.

    To edit your applications

  • Log in to the iCity API Portal as a developer or OrgAdmin.
          
  • From the Dashboard, select Applications in the navigation sidebar. The list of your applications displays.
          
  • Choose a task from the following table:



    APIs Explorer


    APIs Explorer lets developers interactively discover APIs.

    By making choices from among your API's valid resources and methods, and then submitting queries and viewing responses, developers can gain a better understanding of not only how your APIs work, but also the authentication methods required to access them.

    Using an API Explorer


    Use an API Explorer to test or change an API resource by sending a request. You can also view the queries sent that generated the response as well as code samples. Any published API with a WADL attached to it is automatically pre-populated into the API.

    Because authentication methods are used to control access to each API resource on the server side, valid credentials are required in order to test the API.

    To test applications via APIs Explorer

    Log in to the API Portal. The API Portal for your organization is displayed.
    On the menu bar, click Documentation to access the Documentation page.

    Click iCity API Explorer or 3.11 API Explorer on the navigation sidebar.



    The API Key drop-down displays:



    To test an application with an API key, choose the application from the API Key drop-down list. This pre-populates the API Key value and API Key secret of the chosen application in the Service Authentication dialogue box.


    Note: If there is no API key for the application, a message displays stating "No API key is available." In order to test an API key, the API key must be generated on the iCity API Portal.



    Click [Execute Request]. The results are displayed in the Response tab.

    After viewing the response in the Response tab, you can choose to do the following:

  • To view the request sent to the server, click [Request].
          
  • To view the query sent to the server, click [Query].


    The Query tab displays the following:
          
  • Raw request that contains the HTTP request method.
          
  • Full request URL, including the query parameters.
          
  • Request headers.
          
  • Request body (if available).
          
  • Code samples (see below).



    Example Response




    Example Query




    Working with Code Samples


    Once you have executed a request, you can view or copy code samples.

    To view or copy Code Samples




    1. Click the [Query] tab.
            
    2. Select a language to display the code sample in from the Show Code Sample... drop-down menu.
            
    3. To select code, click [Select Code].
            
    4. To copy and paste the selected code, use the standard [Ctrl] + C and [Ctrl] + V keyboard commands.




    Authenticating an API


    In order for a request to execute correctly, an API must be authenticated on the iCity Gateway. Four authentication methods are available:

  • API Key (currently the only option).
          
  • HTTP Basic.
          
  • OAuth 1.0.
          
  • OAuth 2.0.



    To view or copy Code Samples

  • From the API Explorer page, select the API to authenticate.
          
  • Click [Authentication].
          
  • Choose API Key from the Service Authentication drop-down list.


    Note: If you selected an application from the API Key drop-down list, the next 2 steps below are not necessary, because the API Key Name and Value will be pre-populated in these fields.
  • Enter the Name of the API Key to add. This field is required.
          
  • Enter the Value of the API Key to add. This field is required. The API key must be generated on the iCity API Portal.
          
  • Select whether the API Key Type is part of the Query parameter, or part of the request Header.
          
  • Click [OK] to validate your input and add it to the request.