Chapter 5. Working With the Platform Using FHC

5.1. Managing API Keys with FHC

When certain FHC commands are executed, it needs to communicate with the platform using the user’s identity. This requires the user to login to the platform using the fhc login command. User API keys provides an alternative way to use FHC. You don’t have to run the login command anymore if you have set the user API key in FHC. FHC can use the user’s API key to authenticate when communicating with the platform.

5.1.1. Set User API Keys

In FHC, the command related to API keys management is fhc keys. If you run this command without any additional argument, you will be shown the command help.

To set a user API key for the current FHC target, you should enter the following command: 

fhc keys user target eb8d9b9ea050b9b23fea59e50ba281c67f3715e5
Note

This requires you to have previously set the target using fhc target.

To check which API key is currently used for FHC, you can run this command 

fhc keys user target

After setting a user API key in FHC, you can run other FHC commands as usual.

For example, you can list, create, update and revoke user API keys using FHC.

5.1.2. List User API Keys

If you have logged in or set the user API key using FHC, you can see all the API keys associated with the current user by running this command: 

fhc keys user list

If the output format is set to json in your FHC config, each key object will look like this: 

{
  "key": "eb8d9b9ea050b9b23fea59e50ba281c67f3715e5",
  "keyReference": "1j6qcwiziRkbYy6sUUHDooAY",
  "keyType": "user",
  "label": "test 1",
  "revoked": "2012-04-20T15:18:17.258Z",
  "revokedBy": "1j6qcwiziRkbYy6sUUHDooAY",
  "revokedEmail": "dev@example.com"
}

5.1.3. Create User API Keys

To create a user API key, run this command: 

fhc keys user create test2

You should get a response similar to: 

{
  "key": "22d0c0ac5990e8fd2c466c26db1a9eff8a171511",
  "keyReference": "1j6qcwiziRkbYy6sUUHDooAY",
  "keyType": "user",
  "label": "test2",
  "revoked": "",
  "revokedBy": "",
  "revokedEmail": ""
}

5.1.4. Update User API Keys

To update a user API key using FHC, you can run this command: 

fhc keys user update 22d0c0ac5990e8fd2c466c26db1a9eff8a171511 test3

You should get a response similar to: 

{
  "key": "22d0c0ac5990e8fd2c466c26db1a9eff8a171511",
  "keyReference": "1j6qcwiziRkbYy6sUUHDooAY",
  "keyType": "user",
  "label": "test3",
  "revoked": "",
  "revokedBy": "",
  "revokedEmail": ""
}

5.1.5. Revoke User API Keys

To revoke a user API key using FHC, you can run this command: 

fhc keys user revoke 22d0c0ac5990e8fd2c466c26db1a9eff8a171511

You will be prompted to confirm the revoke action. After confirmation, you should see something similar to: 

{
  "key": "22d0c0ac5990e8fd2c466c26db1a9eff8a171511",
  "keyReference": "1j6qcwiziRkbYy6sUUHDooAY",
  "keyType": "user",
  "label": "test3",
  "revoked": "2012-04-20T16:14:11.702Z",
  "revokedBy": "1j6qcwiziRkbYy6sUUHDooAY",
  "revokedEmail": "dev@example.com"
}

5.2. Create a service using FHC

Overview

This tutorial shows you how to create a service and associate it with a project. For more information regarding services, and their functionality, see the Cloud Services documentation.

Requirements

The user must be a member of one or more teams with the following permissions:

  • Project (View & Edit)
  • Service (View & Edit)

For more information on Permissions, see Teams & Collaborations.

5.2.1. Log in to the platform

fhc login myUsername myPassword

5.2.2. Create a Project

Now that you have successfully logged in to the platform, we will create a project that we will then associate a service with. In order to create the project, enter the following command: 

fhc projects create serviceProject

To verify that the project has successfully been created, enter the following command to search for projects on the domain: 

fhc projects | grep 'serviceProject'

This should return the newly created project. Notice that there are currently two apps in this project. A Client App, and a Cloud App.

5.2.3. Create a Service

Services can be added to a project to allow the Client to access back-end functionality they would otherwise not have access to. Before we create a service, we will view a list of available templates. To view the service templates, enter the following command: 

fhc templates services

This will output a list of all available service templates. We will add the PayPal service to the project. To do this, copy the service id of the PayPal service.

When creating a service, we must also specify a name. Enter the following command: 

fhc services create paypalService paypal

This has successfully created a new service that can be associated with Projects.

5.3. Viewing App Stats with FHC

FHC can be used to access raw, JSON stats data for your apps.

To access your app stats (timers and counters) for a particular app, use the following command: 

fhc stats <APP_ID> app <NUMBER_OF_RESULTS>

Where APP_ID is the ID of your app as listed in an fhc apps command, and NUMBER_OF_RESULTS is the maximum number of results you wish to see returned. See below for a sample Stats response. 

{
  interval: 10000,
  results: [
    {
      "ts": 1333107734000,
      "numStats": 6,
      "counters": [
        {
          "key": "DOMAIN_APPID_api_FUNCTIONNAME_active_requests",
          "value": {
            "value": 3,
            "valuePerSecond": 0.3
          }
        },
        {
          "key": "DOMAIN_APPID_api_FUNCTIONNAME2_active_requests",
          "value": {
            "value": 27,
            "valuePerSecond": 2.7
          }
        },
        {
          "key": "DOMAIN_APPID_api_FUNCTIONNAME3_active_requests",
          "value": {
            "value": 456,
            "valuePerSecond": 45.6
          }
        }
      ],
      "timers": [
        {
          "key": "DOMAIN_APPID_api_FUNCTIONNAME_request_times",
          "value": {
            "upper": 86,
            "lower": 63,
            "count": 17,
            "pcts": [
              {
                "pct": "90",
                "value": {
                  "mean": 76,
                  "upper": 86
                }
              }
            ]
          }
        },
        {
          "key": "DOMAIN_APPID_api_FUNCTIONNAME2_request_times",
          "value": {
            "upper": 99,
            "lower": 82,
            "count": 41,
            "pcts": [
              {
                "pct": "90",
                "value": {
                  "mean": 88.66666666666667,
                  "upper": 99
                }
              }
            ]
          }
        },
        {
          "key": "DOMAIN_APPID_api_FUNCTIONNAME3_request_times",
          "value": {
            "upper": 99,
            "lower": 75,
            "count": 2783,
            "pcts": [
              {
                "pct": "90",
                "value": {
                  "mean": 79.1254547827,
                  "upper": 99
                }
              }
            ]
          }
        }
      ]
    }
  ]
}